File Manager

This page lists and describes the File Manager category of endpoints within the Content Services API. It also includes interactive testing environments for each endpoint in this category.

File Manager endpoints are part of the Content Services API. The Content Services API is available on Beefree SDK plans that are Essentials or above.

Overview

The File Manager endpoints let your application manage an end user's files and folders from your own server, without opening a builder. They act on the same file system the File Manager displays inside the editor, so anything your application changes through the API your end users will see next time they open it.

A single resource family, /v1/file, covers six operations. The following table lists them.

Operation	Request
List a directory	GET /v1/file/{path}/
Search files	GET /v1/file/{path}?q={query}
Create a directory	POST /v1/file/{path}/
Upload a file	POST /v1/file/{path}/{filename}
Move a file	PATCH /v1/file/{path}/{filename}
Delete a file or directory	DELETE /v1/file/{path}/{filename} or DELETE /v1/file/{path}/

Everything after /v1/file/ is the path to a file or directory inside your end user's storage, and a trailing slash decides which of the two a request addresses. Reference the Paths and the trailing slash section before you write against these endpoints.

Each request counts as one Content Services API call, and these endpoints are subject to the same rate limits as every other category.

Headers and authentication

Every request carries your Content Services API key as a bearer token, plus a header identifying the end user whose files you're working with.

Authorization: Bearer {your API key}
X-BEE-Uid: {end-user id}

If your application already calls the Content Services API, your existing key works on these endpoints and there's nothing new to provision. Reference the Authentication page to learn more about creating and managing keys. A missing or invalid Authorization header returns 401.

Identify the end user

X-BEE-Uid is the same uid your application uses when it creates an editor session, so the API and the editor resolve to the same file system. It's required on every call, including a listing of the storage root. A uid that has never been used before works fine, since the value identifies a customer of yours rather than a Beefree SDK account, and we don't validate it.

If the header is missing or empty, the request fails with 400:

{
  "code": 3750,
  "message": "Request Error",
  "details": "Missing x-bee-uid header"
}

Other headers

CDN segmentation, custom domains, and custom file system providers each require additional headers. Send the ones for each feature your application has configured. If you don't use any of them, Authorization and X-BEE-Uid are all you need. The following table lists the headers by feature.

Feature	Headers
CDN segmentation	X-BEE-TENANT-IDENTIFIER
Custom file system provider	X-BEE-BUSINESSUID, X-BEE-DOCUMENT-ID, X-BEE-CUSTOM-HOST, X-BEE-AUTHORIZATION
Custom domain	X-BEE-CUSTOM-THIRD-LEVEL-DOMAIN, X-BEE-CUSTOM-DOMAIN, X-BEE-CUSTOM-MEDIA-DOMAIN

X-BEE-AUTHORIZATION carries the credentials for your own file system provider, not for Beefree SDK. Your Content Services API key always goes in the Authorization header.

These endpoints are server-to-server only

These endpoints accept a Content Services API key only. The access token your backend obtains from /loginV2 to start a builder session doesn't work here, and sending one returns 403:

{
  "status": 403,
  "code": 403,
  "message": "Resource forbidden: API token required."
}

Keep secrets on the server. Never expose your Client Secret or Content Services API key to the browser. Calling these endpoints from a browser would expose your API key.

Storage requirements

These endpoints require your application's file storage provider to be updated to the latest version. Requests from an application on an earlier version return 422:

{
  "code": 3621,
  "message": "Storage configuration error: feature available only on FSPx"
}

If you see this error, contact our team and we'll confirm which version your application is on.

Moving files can also be disabled for an individual storage. When it is, Move a file returns 422 with code 3622, and files come back from a listing with extra.can-move set to false.

Paths and the trailing slash

Everything after /v1/file/ is the path inside the end user's storage.

The trailing slash chooses the operation

A trailing slash means directory, and no trailing slash means file. This single character changes what a request does. The following table shows the same route with and without it.

Request	Result
POST /v1/file/campaigns/	Creates the directory campaigns
POST /v1/file/campaigns/hero.jpg	Uploads the file hero.jpg into campaigns
DELETE /v1/file/campaigns/	Deletes campaigns if it's empty
DELETE /v1/file/campaigns/hero.jpg	Deletes the single file hero.jpg
PATCH /v1/file/campaigns/	Refused, because only files can be moved

On GET the trailing slash isn't enforced, so GET /v1/file/campaigns and GET /v1/file/campaigns/ both work. The path is forwarded as given and normalized by the storage service.

The storage root and reserved directories

What the root contains depends on whether your application has a Customer Shared Folder configured.

With a Customer Shared Folder, the root holds two directories and nothing else. Your end user's own files live in /myfiles, where every operation is available. The shared files live in /shared, which supports listing and searching only; creating, uploading, moving, and deleting return an error. Neither directory can be deleted.

Without one, your end users work directly in the root, uploading files and creating directories there.

Either way, the root itself can't be created, moved, or deleted.

• GET /v1/file and GET /v1/file/ both list the root.

• POST /v1/file, PATCH /v1/file, and DELETE /v1/file return 404, because there's no such route.

• POST /v1/file/, PATCH /v1/file/, and DELETE /v1/file/ return 400 with a details message explaining that a path is required.

To upload to the root, use a single-segment path: POST /v1/file/hero.jpg.

Valid paths

Path segments are validated and re-encoded before they're forwarded to storage.

Paths and file names can contain spaces, &, %, non-ASCII characters, and emoji. /my folder/a&b.txt and /😀/x.png are both valid, and a literal % stays a literal %.

Two things are rejected with 400 and details of Invalid path:

• Any . or .. segment, including percent-encoded forms such as %2e%2e%2f.

• An empty inner segment, which means a leading // as in //foo, or a repeated slash as in a//b. A repeated slash matters because a//b addresses a different location in storage than a/b.

Paths are case-sensitive, and so is the route itself. /V1/File/... returns 404.

Responses and errors

A successful call returns 200, with the payload of the operation in data. For a listing or a search, data carries the items. For a write operation, it carries the metadata of what you wrote.

{
  "status": "success",
  "data": { }
}

Read code, not just the HTTP status

Three different error bodies can reach your client, so read code rather than relying on the status alone. Logical failures, such as a name collision or a missing source file, arrive as 400 with the storage error body preserved.

code	Raised by	Where the detail is
3750	The API layer rejecting the request	details, a string. message is always Request Error
3500	Field validation in the storage layer	details, an object with one key per invalid field
Anything else	Storage or your file storage provider, such as 3400 for a collision or 3200 for a missing file	message. details may be present but empty

{
  "code": 3750,
  "message": "Request Error",
  "details": "conflict_strategy is required and must be one of keep, replace, ask"
}

HTTP status codes

The following table lists the statuses these endpoints return.

Status	Meaning
200	Success
400	The request was rejected with code 3750, a field failed validation, or the operation failed logically and the body carries its own code
401	Authorization missing or invalid
403	An access token was used instead of an API key
404	No such route, which means a bare /v1/file on POST, PATCH, or DELETE, or a wrong-cased path
413	Upload body larger than the maximum upload size
422	Rejected by storage, such as 3621 when the file storage provider needs updating, 3622 when moving is disabled, or 4220 for a dangerous file
429	Rate limit exceeded. The body is plain text, not the JSON envelope
500	Unexpected failure

List a directory

get

Use this endpoint to return the contents of a directory in an end user's File Manager storage. GET /v1/file lists the storage root. Adding a q parameter turns this same call into a search.

How it works

To list an end user's files:

1. Set the path to the directory you want to read.

2. Send the request with your API key and the end user's X-BEE-Uid.

3. Read the directory contents from items, and the directory's own metadata from meta.

Notes

• Listings return every item in the directory. There's no pagination.

• Any query parameter other than q, including a lone mode, isn't forwarded.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pathstringRequired

The directory to list, inside the end user's storage. Use an empty path to list the storage root.

Example: campaigns/

Header parameters

X-BEE-UidstringRequired

The end user whose file system the request applies to. This is the same uid your application uses when it creates an editor session.

Example: your-end-user-id

Responses

200

Successful response

application/json

statusstringOptional

success on a successful call

400

Bad request. A storage-side failure, such as the directory not existing, is also returned here with the storage error body forwarded unchanged.

application/json

401

Authorization header missing or invalid

403

An access token was used instead of a Content Services API key

422

Rejected by storage

application/json

429

Rate limit exceeded. The body is plain text, not the JSON envelope

500

Internal Server Error

get/v1/file/{path}

GET /v1/file/{path} HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
X-BEE-Uid: your-end-user-id
Accept: */*

{
  "status": "success",
  "data": {
    "items": [
      {
        "name": "a.png",
        "path": "/a.png",
        "last-modified": 1787731356313,
        "permissions": "rw",
        "extra": {
          "can-move": false
        },
        "mime-type": "image/png",
        "size": 15315,
        "public-url": "https://domain/path/a.png",
        "thumbnail": "https://domain/path/a.png_thumb.png"
      }
    ],
    "meta": {
      "name": "root",
      "path": "/",
      "last-modified": 1787731356313,
      "permissions": "rw",
      "extra": {},
      "mime-type": "application/directory",
      "size": 0,
      "item-count": 1,
      "item-count-details": {
        "dirs": 0,
        "files": 1
      }
    }
  }
}

Search files

get

Use this endpoint to search an end user's File Manager files by name. Search isn't a separate endpoint: adding q to a listing URL turns that call into a search, and the path in the URL is the scope. Use the bare root to search the whole storage, or a path to search that directory and its subtree.

Search runs against Beefree SDK's own file system, so it isn't available on applications configured with custom storage. Those requests return 422 with code 3621. The other five operations are unaffected.

How it works

To search an end user's files:

1. Set the path to the directory you want to search, or use the bare root to search everything.

2. Pass the search term as q, and optionally a mode to change how names are matched.

3. Read the matches from items, and check truncated to see whether the result set was cut off.

Matching modes

Mode	Matches
exact	The file name matches the query
prefix	The file name starts with the query. q=sum matches summer.jpg and summit-banner.png
contains	The query appears anywhere in the file name. q=banner matches summer-banner.jpg and top-banner-2025.png
fuzzy	File names a few characters different from the query, which makes it tolerant of typos

Fuzzy matching reliably tolerates one or two character differences per token, and up to three when they are spread across a multi-word query. Use prefix or contains when your application knows the naming convention it is looking for, since both give predictable results.

Notes

• A search returns at most 200 matches. When more files match, truncated is true, which tells you the result set is incomplete rather than empty. There's no pagination, so narrow the query or search a deeper path to get a complete result.

• All four modes compare the query against file names. Search doesn't read file contents, and it doesn't match on meaning, so a query of product photos won't return a file named hero-banner.jpg however closely related the two are.

• path can't be passed as a query parameter, because the scope always comes from the URL. Sending ?path= returns 400. There's no reserved URL segment either, so a directory named search is an ordinary scope.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pathstringRequired

The directory to search, inside the end user's storage. Use an empty path to search the whole storage.

Example: campaigns/2026

Query parameters

qstringRequired

The search term, minimum three characters. Its presence is what selects search. Must appear exactly once.

Example: hero-banner

modestring · enumOptional

How file names are matched. exact matches the whole name, prefix matches names starting with the query, contains matches the query anywhere in the name, and fuzzy tolerates typos. Must appear at most once.

Default: exactPossible values:

Header parameters

X-BEE-UidstringRequired

The end user whose file system the request applies to. This is the same uid your application uses when it creates an editor session.

Example: your-end-user-id

Responses

200

Successful response

application/json

statusstringOptional

400

Bad request

application/json

401

Authorization header missing or invalid

403

An access token was used instead of a Content Services API key

422

Rejected by storage

application/json

429

Rate limit exceeded. The body is plain text, not the JSON envelope

500

Internal Server Error

get/v1/file/{path}

GET /v1/file/{path}?q=hero-banner HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
X-BEE-Uid: your-end-user-id
Accept: */*

{
  "status": "success",
  "data": {
    "mode": "contains",
    "path": "./campaigns/2026",
    "truncated": false,
    "items": [
      {
        "name": "hero-banner.jpg",
        "path": "./campaigns/2026/hero-banner.jpg",
        "mime-type": "image/jpeg",
        "size": 123,
        "last-modified": 1786714060073,
        "public-url": "https://example.com/hero-banner.jpg",
        "thumbnail": "https://example.com/hero-banner_thumb.jpg"
      }
    ]
  }
}

Create a directory

post

Use this endpoint to create a directory in an end user's File Manager storage. The trailing slash is mandatory, because without it the same route uploads a file.

How it works

To create a folder in an end user's storage:

1. Set the path to the directory you want to create, ending with a slash.

2. Send the request with no body and no query parameters.

3. Read the new directory's metadata from meta.

Notes

• Creating a/b/c/ when a/b/ doesn't exist creates the whole chain.

• The body must be empty. A body on a directory path is rejected, because forwarding it would make the storage create a directory where you meant to upload a file.

• conflict_strategy isn't accepted here.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pathstringRequired

The directory to create, inside the end user's storage.

Example: campaigns/2026

Header parameters

X-BEE-UidstringRequired

The end user whose file system the request applies to. This is the same uid your application uses when it creates an editor session.

Example: your-end-user-id

Responses

200

Successful response

application/json

statusstringOptional

success on a successful call

400

Bad request

application/json

401

Authorization header missing or invalid

403

An access token was used instead of a Content Services API key

404

No such route, which means POST /v1/file with no path at all. No response body

422

Rejected by storage

application/json

429

Rate limit exceeded. The body is plain text, not the JSON envelope

500

Internal Server Error

post/v1/file/{path}/

POST /v1/file/{path}/ HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
X-BEE-Uid: your-end-user-id
Accept: */*

{
  "status": "success",
  "data": {
    "meta": {
      "name": "subfolder",
      "path": "/myfolder/subfolder/",
      "last-modified": 1787752226960,
      "permissions": "rw",
      "extra": {},
      "mime-type": "application/directory",
      "size": 0,
      "item-count": 0,
      "item-count-details": {
        "dirs": 0,
        "files": 0
      }
    }
  }
}

Upload a file

post

Use this endpoint to upload a file to an end user's File Manager storage. The last path segment is the file name and everything before it is the destination directory, so there must be no trailing slash. To upload to the storage root, use a single-segment path: POST /v1/file/{filename}.

The stored name always comes from the URL. File names may contain spaces, &, %, and emoji.

How it works

To upload a file to an end user's storage:

1. Set the path to the destination directory and file name, with no trailing slash.

2. Choose a conflict_strategy and add it to the query string.

3. Send the file as raw bytes, as multipart form data, or as a URL for Beefree SDK to fetch.

4. Read the stored file's metadata, including its public-url, from meta.

Choose what happens on a collision

conflict_strategy is mandatory, so collision behavior is always an explicit choice rather than a default you inherit.

Value	Behavior
keep	The existing file is preserved and the new one is numbered. If a.png exists, the upload is stored as a_1.png
replace	The existing file is overwritten
ask	The call fails with 400 and {"code": 3400, "message": "Resource Already Present"}

Three ways to send the file

The Content-Type header selects the upload mode.

1. Raw bytes. Set Content-Type to the file's own MIME type, such as image/jpeg or application/pdf, and send the bytes as the body. The Content-Type has to be a well-formed type/subtype.

2. Multipart form data. Send a normal multipart/form-data body. A boundary parameter is mandatory, and without it the request is rejected. The part name and any filename inside the multipart body are ignored, since the stored name comes from the URL.

3. From a URL. Set Content-Type: application/json and send {"url": "https://..."}. The file is fetched server-side, so no bytes travel through the API. The URL has to be an absolute http or https URL, can't contain a comma, and can be at most 20,000 characters.

The URL mode is the one to reach for when an AI agent or an external service has already produced a file and given you a link to it.

Notes

• The maximum upload size is 20 MB by default, and it applies to all three upload modes. A larger body returns 413.

• The response carries the file's public-url, so an application that captures it here doesn't need a follow-up search to find the file it just uploaded.

• The body is validated before conflict_strategy, so a malformed upload is told about its actual problem first.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pathstringRequired

The destination directory, inside the end user's storage.

Example: campaigns/2026

filenamestringRequired

The name the file is stored under. Always taken from the URL, never from the request body. May contain spaces, ampersands, percent signs, and emoji.

Example: hero-banner.jpg

Query parameters

conflict_strategystring · enumRequired

What to do when a file of that name already exists. keep preserves the existing file and numbers the new one, so a.png becomes a_1.png. replace overwrites the existing file. ask fails with Resource Already Present. Must appear exactly once.

Example: keepPossible values:

Header parameters

X-BEE-UidstringRequired

The end user whose file system the request applies to. This is the same uid your application uses when it creates an editor session.

Example: your-end-user-id

Body

urlstringRequired

Absolute http or https URL for Beefree SDK to fetch the file from. Cannot contain a comma, and can be at most 20,000 characters.

Responses

200

Successful response

application/json

statusstringOptional

success on a successful call

400

Bad request

application/json

401

Authorization header missing or invalid

403

An access token was used instead of a Content Services API key

413

Payload too large

application/json

422

Rejected by storage

application/json

429

Rate limit exceeded. The body is plain text, not the JSON envelope

500

Internal Server Error

post/v1/file/{path}/{filename}

POST /v1/file/{path}/{filename}?conflict_strategy=keep HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
X-BEE-Uid: your-end-user-id
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "url": "https://example.com/generated-image.jpg"
}

{
  "status": "success",
  "data": {
    "meta": {
      "name": "hero-banner.jpg",
      "path": "/hero-banner.jpg",
      "last-modified": 1787715984545,
      "permissions": "rw",
      "extra": {
        "can-move": true
      },
      "mime-type": "image/jpeg",
      "size": 15315,
      "public-url": "https://domain/path/hero-banner.jpg",
      "thumbnail": "https://domain/path/hero-banner.jpg._thumb.jpg"
    }
  }
}

Move a file

patch

Use this endpoint to move a file into a different directory in an end user's File Manager storage, keeping its file name.

This endpoint moves files only, and it doesn't rename them. A path ending in / is refused, because directories can't be moved. new_directory is always a destination directory rather than a target file name, so there's no way to rename a file in the same call.

How it works

To move a file:

1. Set the path to the file you want to move.

2. Choose a conflict_strategy and add it to the query string.

3. Send a JSON body naming the destination directory.

4. Read the file's new metadata from meta.

Notes

• conflict_strategy belongs in the query string. Sending it inside the JSON body returns 400 with details of Unexpected field in the request body: conflict_strategy. It takes the same keep, replace, and ask values as an upload.

• new_directory accepts optional leading and trailing slashes, which are stripped, and surrounding whitespace is trimmed. A value of / means the storage root.

• If the destination directory doesn't exist, it is created.

• No field other than new_directory is accepted, and an unexpected field returns 400 naming it.

• Unlike the URL path, new_directory isn't pre-decoded, so a literal % has to be sent as % rather than %25.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pathstringRequired

The directory the file is currently in.

Example: campaigns/2026

filenamestringRequired

The file to move. The file keeps this name in its new directory.

Example: hero.jpg

Query parameters

conflict_strategystring · enumRequired

What to do when a file of that name already exists in the destination. Accepted values are keep, replace, and ask. Must appear exactly once, in the query string. Sending it in the request body returns 400.

Example: keepPossible values:

Header parameters

X-BEE-UidstringRequired

The end user whose file system the request applies to. This is the same uid your application uses when it creates an editor session.

Example: your-end-user-id

Body

new_directorystringRequired

The destination directory, non-empty. Leading and trailing slashes are optional and stripped, and surrounding whitespace is trimmed. A value of / means the storage root. No other field is accepted.

Responses

200

Successful response

application/json

statusstringOptional

success on a successful call

400

Bad request

application/json

401

Authorization header missing or invalid

403

An access token was used instead of a Content Services API key

404

No such route, which means PATCH /v1/file with no path at all. No response body

422

Rejected by storage

application/json

429

Rate limit exceeded. The body is plain text, not the JSON envelope

500

Internal Server Error

patch/v1/file/{path}/{filename}

PATCH /v1/file/{path}/{filename}?conflict_strategy=keep HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
X-BEE-Uid: your-end-user-id
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "new_directory": "archive/2026"
}

{
  "status": "success",
  "data": {
    "meta": {
      "name": "hero.jpg",
      "path": "/hero.jpg",
      "last-modified": 1787316444012,
      "permissions": "rw",
      "extra": {
        "can-move": true
      },
      "mime-type": "image/jpeg",
      "size": 8642,
      "public-url": "https://domain/path/hero.jpg",
      "thumbnail": "https://domain/path/hero.jpg_thumb.jpg"
    }
  }
}

Delete a file or directory

delete

Use this endpoint to delete the file or directory at the path.

A directory is deleted only when it is empty, so DELETE /v1/file/campaigns/ removes campaigns only if it contains no files. To clear a folder, delete its files first and then the folder.

How it works

To delete a file or folder:

1. Set the path to the file, or to the directory with a trailing slash.

2. Send the request with no body and no query parameters.

3. Check for a 200 response, which returns null in data.

Notes

• Address a directory with a trailing slash and a file without one.

• The storage root can't be deleted.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

pathstringRequired

The directory the file is in, inside the end user's storage.

Example: campaigns/2026

filenamestringRequired

The file to delete. To delete an empty directory instead, end the path with a trailing slash and omit the file name.

Example: hero-banner.jpg

Header parameters

X-BEE-UidstringRequired

The end user whose file system the request applies to. This is the same uid your application uses when it creates an editor session.

Example: your-end-user-id

Responses

200

Successful response

application/json

statusstringOptional

dataany · nullableOptional

null on a successful delete

400

Bad request

application/json

401

Authorization header missing or invalid

403

An access token was used instead of a Content Services API key

404

No such route, which means DELETE /v1/file with no path at all. No response body

422

Rejected by storage

application/json

429

Rate limit exceeded. The body is plain text, not the JSON envelope

500

Internal Server Error

delete/v1/file/{path}/{filename}

DELETE /v1/file/{path}/{filename} HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
X-BEE-Uid: your-end-user-id
Accept: */*

{
  "status": "success",
  "data": null
}

Limitations

Consider the following when working with the File Manager endpoints:

• Every operation requires your application's file storage provider to be updated to the latest version.

• Directories can't be moved, and files can't be renamed.

• A directory is deleted only when it's empty.

• Search matches file names, not file contents or meaning, and returns at most 200 results with no pagination.

• Search isn't available on applications configured with custom storage.

• Listings return every item in a directory, with no pagination.

• The default maximum upload size is 20 MB.

• Creating, uploading, moving, and deleting are unavailable in the Customer Shared Folder (/shared).