From 3cb3802da6820fde33963aad860423fbc98b6831 Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Wed, 23 Jul 2025 11:35:52 +0200
Subject: [PATCH 01/15] Initialization section updates
Clearer examples and addition of error message if baseURL is missing protocol
---
docusaurus/docs/cms/api/client.md | 23 ++++++++++++++++++++++-
1 file changed, 22 insertions(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index 2875b562d4..a5d0fd4e6f 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -51,12 +51,28 @@ To use the Strapi Client in your project, install it as a dependency using your
To start interacting with your Strapi back end, initialize the Strapi Client and set the base API URL:
+#### Javascript
+
+Require the `strapi` function and create a client instance:
+
```js
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
+#### TypeScript / ESM
+
+Import the `strapi` function and create a client instance with your Strapi API base URL:
+
+```typescript
+import { strapi } from '@strapi/client';
+
+const client = strapi({ baseURL: 'http://localhost:1337/api' });
+```
+
+#### Browser (UMD)
+
If you're using the Strapi Client in a browser environment, you can include it using a `
```
+The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError` [[source]](https://github.com/strapi/client/blob/f4a5d0dad9de23513f572700bc48ba9f1bafb3a9/README.md).
+
### Authentication
The Strapi Client supports different authentication strategies to access protected resources in your Strapi back end.
@@ -165,6 +183,9 @@ const updatedHomepage = await homepage.update(
await homepage.delete();
```
+
+
+
### Working with files
The Strapi Client provides access to the [Media Library](/cms/features/media-library) via the `files` property. This allows you to retrieve and manage file metadata without directly interacting with the REST API.
@@ -222,4 +243,4 @@ console.log('Deleted file name:', deletedFile.name);
:::strapi Additional information
More details about the Strapi Strapi Client might be found in the .
-:::
\ No newline at end of file
+:::
From 448683d94cc8605df5a3e71607c9618c5c78a280 Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Wed, 23 Jul 2025 11:40:46 +0200
Subject: [PATCH 02/15] Update Authentication section
Added note that this is the only auth method currently; added error message
---
docusaurus/docs/cms/api/client.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index a5d0fd4e6f..aec903f16a 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -87,7 +87,7 @@ The `baseURL` must include the protocol (`http` or `https`). An invalid URL will
### Authentication
-The Strapi Client supports different authentication strategies to access protected resources in your Strapi back end.
+The Strapi Client currently only supports API tokens as an authentication method, to access protected resources in your Strapi back end.
If your Strapi instance uses API tokens, configure the Strapi Client as follows:
@@ -99,6 +99,7 @@ const client = strapi({
```
This allows your requests to include the necessary authentication credentials automatically.
+If the token is invalid or missing, the client will throw an error during initialization `StrapiValidationError` [[source]](https://github.com/strapi/client/blob/f4a5d0dad9de23513f572700bc48ba9f1bafb3a9/src/index.ts).
## API Reference
From 5037e8d8609fb6c850ad84147d9e696e72d0f2bc Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Wed, 23 Jul 2025 11:43:50 +0200
Subject: [PATCH 03/15] Ditched [source]
Standardising with rest of docs
---
docusaurus/docs/cms/api/client.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index aec903f16a..e48c08d675 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -83,7 +83,7 @@ If you're using the Strapi Client in a browser environment, you can include it u
```
-The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError` [[source]](https://github.com/strapi/client/blob/f4a5d0dad9de23513f572700bc48ba9f1bafb3a9/README.md).
+The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
### Authentication
@@ -99,7 +99,7 @@ const client = strapi({
```
This allows your requests to include the necessary authentication credentials automatically.
-If the token is invalid or missing, the client will throw an error during initialization `StrapiValidationError` [[source]](https://github.com/strapi/client/blob/f4a5d0dad9de23513f572700bc48ba9f1bafb3a9/src/index.ts).
+If the token is invalid or missing, the client will throw an error during initialization `StrapiValidationError`.
## API Reference
From fd07f9c2e49933a708bf8cc44f77b1c3858ecadf Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Wed, 23 Jul 2025 12:12:07 +0200
Subject: [PATCH 04/15] Upload file additions
---
docusaurus/docs/cms/api/client.md | 125 +++++++++++++++++++++++++++++-
1 file changed, 123 insertions(+), 2 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index e48c08d675..e5cf25f674 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -111,6 +111,7 @@ The Strapi Client provides the following key properties and methods for interact
| `fetch()` | A utility method for making generic API requests similar to the native fetch API. |
| `collection()` | Manages collection-type resources (e.g., blog posts, products). |
| `single()` | Manages single-type resources (e.g., homepage settings, global configurations). |
+| `files()` | Enables upload, retrieve and management of files directly to/from the Strapi Media Library. |
### General purpose fetch
@@ -184,10 +185,123 @@ const updatedHomepage = await homepage.update(
await homepage.delete();
```
+## FilesManager use in the Client
+### Media File Upload
+The Strapi Client provides media file upload functionality through the `FilesManager`, accessible as `client.files`.
-### Working with files
+The `client.files.upload()` method allows you to upload media files (such as images, videos, or documents) to your Strapi backend. It supports uploading files as `Blob` (in browsers or Node.js) or as `Buffer` (in Node.js). The method also supports attaching metadata to the uploaded file, such as `alternativeText` and `caption`.
+
+
+### Method Signature
+
+```js
+async upload(file: Blob, options?: BlobUploadOptions): Promise
+async upload(file: Buffer, options: BufferUploadOptions): Promise
+```
+
+- For `Blob` uploads, `options` is optional and may include `fileInfo` for metadata.
+- For `Buffer` uploads, `options` must include `filename` and `mimetype`, and may include `fileInfo`.
+
+The response is an array of file objects, each containing details such as `id`, `name`, `url`, `size`, and `mime` [source](https://github.com/strapi/client/blob/60a0117e361346073bed1959d354c7facfb963b3/src/files/types.ts).
+
+**Usage examples:**
+
+#### Uploading a File in the Browser
+
+```js
+const client = strapi({ baseURL: 'http://localhost:1337/api' });
+
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+try {
+ const result = await client.files.upload(file, {
+ fileInfo: {
+ alternativeText: 'A user uploaded image',
+ caption: 'Uploaded via browser',
+ },
+ });
+ console.log('Upload successful:', result);
+} catch (error) {
+ console.error('Upload failed:', error);
+}
+```
+
+#### Uploading a Blob in Node.js
+
+```js
+import { readFile } from 'fs/promises';
+
+const client = strapi({ baseURL: 'http://localhost:1337/api' });
+
+const filePath = './image.png';
+const mimeType = 'image/png';
+const fileContentBuffer = await readFile(filePath);
+const fileBlob = new Blob([fileContentBuffer], { type: mimeType });
+
+try {
+ const result = await client.files.upload(fileBlob, {
+ fileInfo: {
+ name: 'Image uploaded as Blob',
+ alternativeText: 'Uploaded from Node.js Blob',
+ caption: 'Example upload',
+ },
+ });
+ console.log('Blob upload successful:', result);
+} catch (error) {
+ console.error('Blob upload failed:', error);
+}
+```
+
+#### Uploading a Buffer in Node.js
+
+```js
+import { readFile } from 'fs/promises';
+
+const client = strapi({ baseURL: 'http://localhost:1337/api' });
+
+const filePath = './image.png';
+const fileContentBuffer = await readFile(filePath);
+
+try {
+ const result = await client.files.upload(fileContentBuffer, {
+ filename: 'image.png',
+ mimetype: 'image/png',
+ fileInfo: {
+ name: 'Image uploaded as Buffer',
+ alternativeText: 'Uploaded from Node.js Buffer',
+ caption: 'Example upload',
+ },
+ });
+ console.log('Buffer upload successful:', result);
+} catch (error) {
+ console.error('Buffer upload failed:', error);
+}
+```
+
+
+### Response Structure
+
+The upload method returns an array of file objects, each with fields such as:
+
+```json
+{
+ "id": 1,
+ "name": "image.png",
+ "alternativeText": "Uploaded from Node.js Buffer",
+ "caption": "Example upload",
+ "mime": "image/png",
+ "url": "/uploads/image.png",
+ "size": 12345,
+ "createdAt": "2025-07-23T12:34:56.789Z",
+ "updatedAt": "2025-07-23T12:34:56.789Z"
+}
+```
+
+
+### Managing files
The Strapi Client provides access to the [Media Library](/cms/features/media-library) via the `files` property. This allows you to retrieve and manage file metadata without directly interacting with the REST API.
@@ -242,6 +356,13 @@ console.log('Deleted file ID:', deletedFile.id);
console.log('Deleted file name:', deletedFile.name);
```
+## Handling Common Errors
+
+- **Permission Errors:** If the authenticated user does not have permission to upload or manage files, a `FileForbiddenError` is thrown.
+- **HTTP Errors:** If the server is unreachable, authentication fails, or there are network issues, an `HTTPError` is thrown.
+- **Missing Parameters:** When uploading a `Buffer`, both `filename` and `mimetype` must be provided in the options object. If either is missing, an error is thrown.
+
+
:::strapi Additional information
-More details about the Strapi Strapi Client might be found in the .
+More details about the Strapi Client may be found in the .
:::
From 5d2cd56616533c4775737575aac61dc78d0109f2 Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Wed, 23 Jul 2025 14:59:58 +0200
Subject: [PATCH 05/15] Docusaurus improvements
---
docusaurus/docs/cms/api/client.md | 25 ++++++++++++++++---------
1 file changed, 16 insertions(+), 9 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index e5cf25f674..c9b676a78d 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -51,30 +51,31 @@ To use the Strapi Client in your project, install it as a dependency using your
To start interacting with your Strapi back end, initialize the Strapi Client and set the base API URL:
-#### Javascript
-
-Require the `strapi` function and create a client instance:
+With Javascript, require the `strapi` function and create a client instance:
+
+
```js
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
+
-#### TypeScript / ESM
-Import the `strapi` function and create a client instance with your Strapi API base URL:
+With Typescript, import the `strapi` function and create a client instance with your Strapi API base URL:
+
```typescript
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
+
-#### Browser (UMD)
-
-If you're using the Strapi Client in a browser environment, you can include it using a `
@@ -82,9 +83,10 @@ If you're using the Strapi Client in a browser environment, you can include it u
const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
```
-
+
The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
+
### Authentication
The Strapi Client currently only supports API tokens as an authentication method, to access protected resources in your Strapi back end.
@@ -98,6 +100,7 @@ const client = strapi({
});
```
+
This allows your requests to include the necessary authentication credentials automatically.
If the token is invalid or missing, the client will throw an error during initialization `StrapiValidationError`.
@@ -134,6 +137,8 @@ Collection types in Strapi are entities with multiple entries (e.g., a blog with
| `delete(documentID, queryParams?)` | Update an existing document. |
**Usage examples:**
+
+
```js
const articles = client.collection('articles');
@@ -155,6 +160,8 @@ const updatedArticle = await articles.update('article-document-id', { title: 'Up
// Delete an article
await articles.delete('article-id');
```
+
+
### Working with single types
From edd788da1e7584e1718a17b5c6350a423817ff2c Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Wed, 23 Jul 2025 15:20:54 +0200
Subject: [PATCH 06/15] Fix formatting
---
docusaurus/docs/cms/api/client.md | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index c9b676a78d..bbd94bc43f 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -51,31 +51,35 @@ To use the Strapi Client in your project, install it as a dependency using your
To start interacting with your Strapi back end, initialize the Strapi Client and set the base API URL:
-With Javascript, require the `strapi` function and create a client instance:
+With Javascript, require the `strapi` function and create a client instance:
+
```js
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
+
+
With Typescript, import the `strapi` function and create a client instance with your Strapi API base URL:
-
```typescript
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
+
+
If you're using the Strapi Client in a browser environment, you can include it using a `
@@ -83,9 +87,12 @@ If you're using the Strapi Client in a browser environment, you can include it u
const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
```
+
-The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
+
+
+The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
### Authentication
From f8f75bed13728cc5375ea16eb0a804c122bf2dfe Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Wed, 23 Jul 2025 15:26:32 +0200
Subject: [PATCH 07/15] Revert "Fix formatting"
This reverts commit edd788da1e7584e1718a17b5c6350a423817ff2c.
---
docusaurus/docs/cms/api/client.md | 15 ++++-----------
1 file changed, 4 insertions(+), 11 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index bbd94bc43f..c9b676a78d 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -51,35 +51,31 @@ To use the Strapi Client in your project, install it as a dependency using your
To start interacting with your Strapi back end, initialize the Strapi Client and set the base API URL:
+With Javascript, require the `strapi` function and create a client instance:
-With Javascript, require the `strapi` function and create a client instance:
-
```js
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
-
-
With Typescript, import the `strapi` function and create a client instance with your Strapi API base URL:
+
```typescript
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
-
-
If you're using the Strapi Client in a browser environment, you can include it using a `
@@ -87,13 +83,10 @@ If you're using the Strapi Client in a browser environment, you can include it u
const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
```
-
-
-
-
The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
+
### Authentication
The Strapi Client currently only supports API tokens as an authentication method, to access protected resources in your Strapi back end.
From 817bc84ea81549848a308460a2afecd6e7648901 Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Wed, 23 Jul 2025 17:19:11 +0200
Subject: [PATCH 08/15] Improve structure
so that the new upload-related information better fits with the
existing information architecture
---
docusaurus/docs/cms/api/client.md | 187 +++++++++++++++++++++---------
1 file changed, 130 insertions(+), 57 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index c9b676a78d..6312626d27 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -1,6 +1,7 @@
---
title: Strapi Client
description: The Strapi Client library simplifies interactions with your Strapi back end, providing a way to fetch, create, update, and delete content.
+toc_max_heading_level: 4
displayed_sidebar: cmsSidebar
tags:
- API
@@ -51,20 +52,22 @@ To use the Strapi Client in your project, install it as a dependency using your
To start interacting with your Strapi back end, initialize the Strapi Client and set the base API URL:
-With Javascript, require the `strapi` function and create a client instance:
+With Javascript, require the `strapi` function and create a client instance:
+
```js
import { strapi } from '@strapi/client';
const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
+
+
With Typescript, import the `strapi` function and create a client instance with your Strapi API base URL:
-
```typescript
import { strapi } from '@strapi/client';
@@ -73,9 +76,9 @@ const client = strapi({ baseURL: 'http://localhost:1337/api' });
```
-
-If you're using the Strapi Client in a browser environment, you can include it using a `
@@ -83,7 +86,10 @@ If you're using the Strapi Client in a browser environment, you can include it u
const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
```
+
+
+
The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
@@ -139,6 +145,7 @@ Collection types in Strapi are entities with multiple entries (e.g., a blog with
**Usage examples:**
+
```js
const articles = client.collection('articles');
@@ -160,6 +167,7 @@ const updatedArticle = await articles.update('article-document-id', { title: 'Up
// Delete an article
await articles.delete('article-id');
```
+
@@ -192,16 +200,96 @@ const updatedHomepage = await homepage.update(
await homepage.delete();
```
-## FilesManager use in the Client
+### Working with files
+
+The Strapi Client provides access to the [Media Library](/cms/features/media-library) via the `files` property. This allows you to retrieve and manage file metadata without directly interacting with the REST API.
+
+The following methods are available for working with files. Click on the method name in the table to jump to the corresponding section with more details and examples:
+
+| Method | Description |
+|--------|-------------|
+| [`find(params?)`](#find) | Retrieves a list of file metadata based on optional query parameters |
+| [`findOne(fileId)`](#findOne) | Retrieves the metadata for a single file by its ID |
+| [`update(fileId, fileInfo)`](#update) | Updates metadata for an existing file |
+| [`upload(type, options)`](#upload) | Uploads a file, specifying:- `type` which can be `file`, `fileContentBuffer`, or `fileBlob`
- and an additional `options` object
|
+| [`delete(fileId)`](#delete) | Deletes a file by its ID |
+
+#### `find`
+
+The `strapi.client.files.find()` method retrieves a list of file metadata based on optional query parameters.
+
+The method can be used as follows:
+
+```js
+// Initialize the client
+const client = strapi({
+ baseURL: 'http://localhost:1337/api',
+ auth: 'your-api-token',
+});
+
+// Find all file metadata
+const allFiles = await client.files.find();
+console.log(allFiles);
+
+// Find file metadata with filtering and sorting
+const imageFiles = await client.files.find({
+ filters: {
+ mime: { $contains: 'image' }, // Only get image files
+ name: { $contains: 'avatar' }, // Only get files with 'avatar' in the name
+ },
+ sort: ['name:asc'], // Sort by name in ascending order
+});
+```
+
+#### `findOne`
-### Media File Upload
+The `strapi.client.files.findOne()` method retrieves the metadata for a single file by its id.
-The Strapi Client provides media file upload functionality through the `FilesManager`, accessible as `client.files`.
+The method can be used as follows:
-The `client.files.upload()` method allows you to upload media files (such as images, videos, or documents) to your Strapi backend. It supports uploading files as `Blob` (in browsers or Node.js) or as `Buffer` (in Node.js). The method also supports attaching metadata to the uploaded file, such as `alternativeText` and `caption`.
+```js
+// Initialize the client
+const client = strapi({
+ baseURL: 'http://localhost:1337/api',
+ auth: 'your-api-token',
+});
+// Find file metadata by ID
+const file = await client.files.findOne(1);
+console.log(file.name);
+console.log(file.url);
+console.log(file.mime); // The file MIME type
+```
+
+#### `update`
-### Method Signature
+The `strapi.client.files.findOne()` method updates metadata for an existing filei, accepting 2 parameters, the `fileId`, and an object containing options such as the name, alternative text, and caption for the media.
+
+The methods can be used as follows:
+
+```js
+// Initialize the client
+const client = strapi({
+ baseURL: 'http://localhost:1337/api',
+ auth: 'your-api-token',
+});
+
+// Update file metadata
+const updatedFile = await client.files.update(1, {
+ name: 'New file name',
+ alternativeText: 'Descriptive alt text for accessibility',
+ caption: 'A caption for the file',
+});
+```
+
+
+#### `upload`
+
+The Strapi Client provides media file upload functionality through the `FilesManager`, accessible through the `strapi.client.files.upload()` method. The method allows you to upload media files (such as images, videos, or documents) to your Strapi backend.
+
+The method supports uploading files as `Blob` (in browsers or Node.js) or as `Buffer` (in Node.js only). The method also supports attaching metadata to the uploaded file, such as `alternativeText` and `caption`.
+
+##### Method Signature
```js
async upload(file: Blob, options?: BlobUploadOptions): Promise
@@ -213,9 +301,10 @@ async upload(file: Buffer, options: BufferUploadOptions): Promise
+
-#### Uploading a File in the Browser
+You can upload a file use through the browser as follows:
```js
const client = strapi({ baseURL: 'http://localhost:1337/api' });
@@ -236,7 +325,14 @@ try {
}
```
-#### Uploading a Blob in Node.js
+
+
+
+
+With Node.js, you can either upload a blob or a buffer, as in the following examples:
+
+
+
```js
import { readFile } from 'fs/promises';
@@ -262,7 +358,9 @@ try {
}
```
-#### Uploading a Buffer in Node.js
+
+
+
```js
import { readFile } from 'fs/promises';
@@ -288,10 +386,15 @@ try {
}
```
+
+
+
+
+
-### Response Structure
+##### Response Structure
-The upload method returns an array of file objects, each with fields such as:
+The `strapi.client.files.upload()` method returns an array of file objects, each with fields such as:
```json
{
@@ -307,21 +410,11 @@ The upload method returns an array of file objects, each with fields such as:
}
```
+#### `delete`
-### Managing files
+The `strapi.client.files.delete()` method deletes a file by its ID.
-The Strapi Client provides access to the [Media Library](/cms/features/media-library) via the `files` property. This allows you to retrieve and manage file metadata without directly interacting with the REST API.
-
-The following methods are available for working with files:
-
-| Method | Description |
-|--------|-------------|
-| `find(params?)` | Retrieves a list of file metadata based on optional query parameters |
-| `findOne(fileId)` | Retrieves the metadata for a single file by its ID |
-| `update(fileId, fileInfo)` | Updates metadata for an existing file |
-| `delete(fileId)` | Deletes a file by its ID |
-
-**Usage examples:**
+The method can be used as follows:
```js
// Initialize the client
@@ -330,32 +423,6 @@ const client = strapi({
auth: 'your-api-token',
});
-// Find all file metadata
-const allFiles = await client.files.find();
-console.log(allFiles);
-
-// Find file metadata with filtering and sorting
-const imageFiles = await client.files.find({
- filters: {
- mime: { $contains: 'image' }, // Only get image files
- name: { $contains: 'avatar' }, // Only get files with 'avatar' in the name
- },
- sort: ['name:asc'], // Sort by name in ascending order
-});
-
-// Find file metadata by ID
-const file = await client.files.findOne(1);
-console.log(file.name); // The file name
-console.log(file.url); // The file URL
-console.log(file.mime); // The file MIME type
-
-// Update file metadata
-const updatedFile = await client.files.update(1, {
- name: 'New file name',
- alternativeText: 'Descriptive alt text for accessibility',
- caption: 'A caption for the file',
-});
-
// Delete a file by ID
const deletedFile = await client.files.delete(1);
console.log('File deleted successfully');
@@ -363,11 +430,17 @@ console.log('Deleted file ID:', deletedFile.id);
console.log('Deleted file name:', deletedFile.name);
```
+
+
## Handling Common Errors
-- **Permission Errors:** If the authenticated user does not have permission to upload or manage files, a `FileForbiddenError` is thrown.
-- **HTTP Errors:** If the server is unreachable, authentication fails, or there are network issues, an `HTTPError` is thrown.
-- **Missing Parameters:** When uploading a `Buffer`, both `filename` and `mimetype` must be provided in the options object. If either is missing, an error is thrown.
+The following errors might occur when sending queries through the Strapi Client:
+
+| Error | Description |
+|-------|-------------|
+| Permission Errors | If the authenticated user does not have permission to upload or manage files, a `FileForbiddenError` is thrown. |
+| HTTP Errors|If the server is unreachable, authentication fails, or there are network issues, an `HTTPError` is thrown. |
+| Missing Parameters|When uploading a `Buffer`, both `filename` and `mimetype` must be provided in the options object. If either is missing, an error is thrown. |
:::strapi Additional information
From 447d2007a3204c9050df173ad2aa09cfa2e1d737 Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Wed, 23 Jul 2025 17:27:06 +0200
Subject: [PATCH 09/15] Fix broken anchors
---
docusaurus/docs/cms/api/client.md | 12 +++++-------
1 file changed, 5 insertions(+), 7 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index 6312626d27..4dfa59dc94 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -15,6 +15,7 @@ tags:
The Strapi Client library simplifies interactions with your Strapi back end, providing a way to fetch, create, update, and delete content. This guide walks you through setting up the Strapi Client, configuring authentication, and using its key features effectively.
## Getting Started
+
:::prerequisites
- A Strapi project has been created and is running. If you haven't set one up yet, follow the [Quick Start Guide](/cms/quick-start) to create one.
- You know the URL of the Content API of your Strapi instance (e.g., `http://localhost:1337/api`).
@@ -92,7 +93,6 @@ If you're using the Strapi Client in a browser environment, you can include it u
The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
-
### Authentication
The Strapi Client currently only supports API tokens as an authentication method, to access protected resources in your Strapi back end.
@@ -106,7 +106,6 @@ const client = strapi({
});
```
-
This allows your requests to include the necessary authentication credentials automatically.
If the token is invalid or missing, the client will throw an error during initialization `StrapiValidationError`.
@@ -178,7 +177,7 @@ Single types in Strapi represent unique content entries that exist only once (e.
| ----------| -------------------------------------------------------------------------------------------- |
| `find(queryParams?)` | Fetch the document. |
| `update(documentID, data, queryParams?)` | Update the document. |
-| `delete(queryParams?) ` | Remove the document. |
+| `delete(queryParams?)` | Remove the document. |
**Usage examples:**
```js
@@ -209,7 +208,7 @@ The following methods are available for working with files. Click on the method
| Method | Description |
|--------|-------------|
| [`find(params?)`](#find) | Retrieves a list of file metadata based on optional query parameters |
-| [`findOne(fileId)`](#findOne) | Retrieves the metadata for a single file by its ID |
+| [`findOne(fileId)`](#findone) | Retrieves the metadata for a single file by its ID |
| [`update(fileId, fileInfo)`](#update) | Updates metadata for an existing file |
| [`upload(type, options)`](#upload) | Uploads a file, specifying:- `type` which can be `file`, `fileContentBuffer`, or `fileBlob`
- and an additional `options` object
|
| [`delete(fileId)`](#delete) | Deletes a file by its ID |
@@ -241,7 +240,7 @@ const imageFiles = await client.files.find({
});
```
-#### `findOne`
+#### `findOne` {#findone}
The `strapi.client.files.findOne()` method retrieves the metadata for a single file by its id.
@@ -282,8 +281,7 @@ const updatedFile = await client.files.update(1, {
});
```
-
-#### `upload`
+#### `upload` {#upload}
The Strapi Client provides media file upload functionality through the `FilesManager`, accessible through the `strapi.client.files.upload()` method. The method allows you to upload media files (such as images, videos, or documents) to your Strapi backend.
From dff68b13936b87e86de5a1f363332a0b491ce7e6 Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Thu, 24 Jul 2025 13:24:25 +0200
Subject: [PATCH 10/15] Update docusaurus/docs/cms/api/client.md
Co-authored-by: Jamie Howard <48524071+jhoward1994@users.noreply.github.com>
---
docusaurus/docs/cms/api/client.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index 4dfa59dc94..90795ae346 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -262,7 +262,7 @@ console.log(file.mime); // The file MIME type
#### `update`
-The `strapi.client.files.findOne()` method updates metadata for an existing filei, accepting 2 parameters, the `fileId`, and an object containing options such as the name, alternative text, and caption for the media.
+The `strapi.client.files.update()` method updates metadata for an existing file, accepting 2 parameters, the `fileId`, and an object containing options such as the name, alternative text, and caption for the media.
The methods can be used as follows:
From 6ec3d53a008f6b660447ce8fdb66e5cc2573bdfe Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Thu, 24 Jul 2025 13:24:52 +0200
Subject: [PATCH 11/15] Update docusaurus/docs/cms/api/client.md
Co-authored-by: Jamie Howard <48524071+jhoward1994@users.noreply.github.com>
---
docusaurus/docs/cms/api/client.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index 90795ae346..4a9abb628c 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -210,7 +210,7 @@ The following methods are available for working with files. Click on the method
| [`find(params?)`](#find) | Retrieves a list of file metadata based on optional query parameters |
| [`findOne(fileId)`](#findone) | Retrieves the metadata for a single file by its ID |
| [`update(fileId, fileInfo)`](#update) | Updates metadata for an existing file |
-| [`upload(type, options)`](#upload) | Uploads a file, specifying:- `type` which can be `file`, `fileContentBuffer`, or `fileBlob`
- and an additional `options` object
|
+| [`upload(file, options)`](#upload) | Uploads a file (Blob or Buffer) with an optional `options` object for metadata |
| [`delete(fileId)`](#delete) | Deletes a file by its ID |
#### `find`
From 812d5fa4d1cdcff93343f75564dca33b2fa82d27 Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Thu, 24 Jul 2025 13:27:20 +0200
Subject: [PATCH 12/15] Reverted authentication info change
U&P is usable now (but still not documented here)
---
docusaurus/docs/cms/api/client.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index 4a9abb628c..b8990058e7 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -95,7 +95,7 @@ The `baseURL` must include the protocol (`http` or `https`). An invalid URL will
### Authentication
-The Strapi Client currently only supports API tokens as an authentication method, to access protected resources in your Strapi back end.
+The Strapi Client supports different authentication strategies to access protected resources in your Strapi back end.
If your Strapi instance uses API tokens, configure the Strapi Client as follows:
From d44b9329d0020da0d2f860cf5a7e81c3c366ef2b Mon Sep 17 00:00:00 2001
From: Hannah Paine <151527179+hanpaine@users.noreply.github.com>
Date: Thu, 24 Jul 2025 13:31:49 +0200
Subject: [PATCH 13/15] Review comments
---
docusaurus/docs/cms/api/client.md | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index b8990058e7..258683cad9 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -56,7 +56,7 @@ To start interacting with your Strapi back end, initialize the Strapi Client and
-With Javascript, require the `strapi` function and create a client instance:
+With Javascript, import the `strapi` function and create a client instance:
```js
import { strapi } from '@strapi/client';
@@ -97,7 +97,7 @@ The `baseURL` must include the protocol (`http` or `https`). An invalid URL will
The Strapi Client supports different authentication strategies to access protected resources in your Strapi back end.
-If your Strapi instance uses API tokens, configure the Strapi Client as follows:
+If your Strapi instance uses [API tokens](/cms/features/api-tokens), configure the Strapi Client as follows:
```js
const client = strapi({
@@ -408,6 +408,10 @@ The `strapi.client.files.upload()` method returns an array of file objects, each
}
```
+:::note Additional Response Fields
+The upload response includes additional fields beyond those shown above. See the complete FileResponse interface in the [client source code](https://github.com/strapi/client/blob/main/src/files/types.ts) for all available fields.
+:::
+
#### `delete`
The `strapi.client.files.delete()` method deletes a file by its ID.
From 453df3885e4095da04f71c40671da5e6479fa452 Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Thu, 24 Jul 2025 15:52:48 +0200
Subject: [PATCH 14/15] Update formatting (no title case)
---
docusaurus/docs/cms/api/client.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index 258683cad9..d7c793766e 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -408,7 +408,7 @@ The `strapi.client.files.upload()` method returns an array of file objects, each
}
```
-:::note Additional Response Fields
+:::note Additional response fields
The upload response includes additional fields beyond those shown above. See the complete FileResponse interface in the [client source code](https://github.com/strapi/client/blob/main/src/files/types.ts) for all available fields.
:::
From b8b1a9ee1fb559506615c73d4476bfdbc3b6c084 Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Thu, 24 Jul 2025 15:53:11 +0200
Subject: [PATCH 15/15] Use proper ExternalLink component for link to source
code
---
docusaurus/docs/cms/api/client.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docusaurus/docs/cms/api/client.md b/docusaurus/docs/cms/api/client.md
index d7c793766e..1d4782ff31 100644
--- a/docusaurus/docs/cms/api/client.md
+++ b/docusaurus/docs/cms/api/client.md
@@ -409,7 +409,7 @@ The `strapi.client.files.upload()` method returns an array of file objects, each
```
:::note Additional response fields
-The upload response includes additional fields beyond those shown above. See the complete FileResponse interface in the [client source code](https://github.com/strapi/client/blob/main/src/files/types.ts) for all available fields.
+The upload response includes additional fields beyond those shown above. See the complete FileResponse interface in the for all available fields.
:::
#### `delete`