🤖 Update LLMs files [skip ci]

Author: web-flow

docusaurus/static/llms-full.txt

@@ -1723,6 +1723,7 @@ Source: https://docs.strapi.io/cms/api/client
 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`).
@@ -1738,26 +1739,15 @@ 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:
 
-```js
-
-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 `<script>` tag:
+</Tabs>
 
-```js title="./src/api/[apiName]/routes/[routerName].ts (e.g './src/api/restaurant/routes/restaurant.ts')"
-<script src="https://cdn.jsdelivr.net/npm/@strapi/client"></script>
-
-<script>
-  const client = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
-</script>
-```
+The `baseURL` must include the protocol (`http` or `https`). An invalid URL will throw an error `StrapiInitializationError`.
 
 ### Authentication
 
 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({
@@ -1767,6 +1757,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`.
 
 ## API Reference
 
@@ -1778,6 +1769,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
 
@@ -1800,27 +1792,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');
 
-// Fetch all english articles sorted by title
-const allArticles = await articles.find({
-  locale: 'en',
-  sort: 'title',
-});
-
-// Fetch a single article
-const singleArticle = await articles.findOne('article-document-id');
-
-// Create a new article
-const newArticle = await articles.create({ title: 'New Article', content: '...' });
-
-// Update an existing article
-const updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });
-
-// Delete an article
-await articles.delete('article-id');
-```
+</Tabs>
 
 ### Working with single types
 
@@ -1829,7 +1802,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
@@ -1851,20 +1824,25 @@ const updatedHomepage = await homepage.update(
 await homepage.delete();
 ```
 
-### Working with files 
+### 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:
+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?)` | 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 |
+| [`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(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 |
 
-**Usage examples:**
+#### `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
@@ -1885,19 +1863,90 @@ const imageFiles = await client.files.find({
   },
   sort: ['name:asc'], // Sort by name in ascending order
 });
+```
+
+#### `findOne` {#findone}
+
+The `strapi.client.files.findOne()` method retrieves the metadata for a single file by its id.
+
+The method can be used as follows:
+
+```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); // The file name
-console.log(file.url); // The file URL
+console.log(file.name);
+console.log(file.url); 
 console.log(file.mime); // The file MIME type
+```
+
+#### `update`
+
+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:
+
+```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` 
+
+</Tabs>
+
+</TabItem>
+</Tabs>
+
+##### Response Structure
+
+The `strapi.client.files.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"
+}
+```
+
+:::note Additional response fields
+The upload response includes additional fields beyond those shown above. See the complete FileResponse interface in the  for all available fields.
+:::
+
+#### `delete`
+
+The `strapi.client.files.delete()` method deletes a file by its ID.
+
+The method can be used as follows:
+
+```js
+// Initialize the client
+const client = strapi({
+  baseURL: 'http://localhost:1337/api',
+  auth: 'your-api-token',
+});
 
 // Delete a file by ID
 const deletedFile = await client.files.delete(1);
@@ -1906,8 +1955,20 @@ console.log('Deleted file ID:', deletedFile.id);
 console.log('Deleted file name:', deletedFile.name);
 ```
 
+<br/>
+
+## Handling Common Errors
+
+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
-More details about the Strapi Strapi Client might be found in the .
+More details about the Strapi Client may be found in the .
 :::