Set where a partner's uploaded files are stored

Points the partner at a bucket of its own on an S3-compatible service (Cloudflare R2, Amazon S3, Wasabi, MinIO and the like). From then on, every file the account that administers the partner stores is kept in that bucket instead of with Widgetic, whichever way it arrives: a file sent with uploadFile (with an API key, an SDK token, an editor session or from the Widgetic website), a resumable upload, the media library, and the files the agent tools and the MCP server save. It takes none of the account’s storage allowance, and its url is served from publicBaseUrl. The chunks of a resumable upload wait in Widgetic’s temporary staging area until it is completed and are removed then: the finished file is stored in your bucket and nowhere else.

A destination is required. Partner storage is not optional: your customers’ files, and your own however they arrive, are kept in this destination and nowhere else. An editor session (createManagedUserEditorSession) of any surface cannot be made until a destination is set (409 PARTNER_STORAGE_REQUIRED), a destination removed later stops the uploads of the sessions already made (the same 409), and your own upload with no destination (on any route, including a resumable upload, which is refused when it is started) is refused in the same way instead of being stored with Widgetic. A partner cannot be activated until it has a destination that works.

The destination is checked before it is saved. Widgetic writes a small test file under <keyPrefix>widgetic-check/, reads it back from <publicBaseUrl>/<its key>, and deletes it. If any step fails nothing is saved and the answer is 422 STORAGE_DESTINATION_UNVERIFIED: details.step says where (endpoint, write or public_read), details.reason says why, and param names the field most likely to be wrong.

What the bucket needs:

• an access key that may put objects into it (it may also delete objects, which lets the test file be cleaned up, but that is not required);
• its files publicly readable at publicBaseUrl, either because the bucket is public or through a CDN.

The secret access key is stored encrypted and is never returned or logged; a response shows only the last four characters of the access key id (accessKeyHint). Saving replaces the whole destination, so send every field again, including the secret. Files already stored stay where they are, and keep working for as long as that bucket stays publicly readable.

Once a destination is set, an upload is never stored with Widgetic instead: when the destination cannot be used the upload is refused with 503 STORAGE_DESTINATION_UNAVAILABLE, and when the bucket rejects the file with 502 STORAGE_DESTINATION_WRITE_FAILED.

The caller must be the person who administers the partner (an API key of that account works); anyone else is refused with 403 whether or not the partner exists. Widgetic administrators can set any partner’s.

PUT /partners/{partnerId}/storage

Set where a partner's uploaded files are stored

cURL

curl --request PUT \
  --url https://api.widgetic.com/v1/partners/{partnerId}/storage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endpoint": "https://abc123.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "acme-widget-media",
  "keyPrefix": "widgetic/",
  "publicBaseUrl": "https://media.example.com",
  "forcePathStyle": true,
  "accessKeyId": "Example accessKeyId",
  "secretAccessKey": "Example secretAccessKey"
}
'

200

{
  "success": true,
  "data": {
    "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "endpoint": "https://abc123.r2.cloudflarestorage.com",
    "region": "auto",
    "bucket": "acme-widget-media",
    "keyPrefix": "widgetic/",
    "publicBaseUrl": "https://media.example.com",
    "forcePathStyle": true,
    "accessKeyHint": "4F2A",
    "verifiedAt": "2026-01-15T09:30:00.000Z",
    "lastVerificationError": "Example lastVerificationError",
    "lastVerificationFailedAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

partnerId · string<uuid> · required

The partner whose storage destination to set

Body

application/json

The bucket to keep the partner's files in, and the key that may write to it. The field names are camelCase, like every answer of the API; the snake_case spelling (keyPrefix) is read too.

endpoint · string · required

The HTTPS address of the S3-compatible service, scheme and host only (no path, port or credentials). It must be a host name, not an IP address, and must resolve to the public internet.

Example:

"https://abc123.r2.cloudflarestorage.com"

region · string · required

The region the service signs requests for. Use auto where the service says so (such as Cloudflare R2).

Example:

"auto"

bucket · string · required

Example:

"acme-widget-media"

publicBaseUrl · string · required

Where the stored files are served from: the bucket's public address, or a CDN in front of it. The address of a file is this value, a slash and the file's key in the bucket, which starts with the key prefix. A path is allowed (https://media.example.com/files/acme-widget-media).

Example:

"https://media.example.com"

accessKeyId · string · required

The id of an access key that may put objects into the bucket

secretAccessKey · string<password> · required · write-only

The secret of that access key. It is stored encrypted and is never returned.

keyPrefix · string · default: ""

A folder inside the bucket to write every file under, for example widgetic/uploads. Folders are made of letters, digits, dots, hyphens and underscores. Leave it out to write at the root of the bucket.

Example:

"widgetic/"

forcePathStyle · boolean · default: true

Put the bucket name in the path of a request. Every S3-compatible service supports this; set it to false only for a service that needs the bucket name in the host name.

Response

200

application/json

The destination passed the check and was saved

success · boolean · required

Always true on a success.

Example:

true

data · object · required

The bucket a partner keeps the files its account uploads in: a bucket on an S3-compatible service that the partner owns. The secret access key is never returned.

Show child attributes

Example:

{
  "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "endpoint": "https://abc123.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "acme-widget-media",
  "keyPrefix": "widgetic/",
  "publicBaseUrl": "https://media.example.com",
  "forcePathStyle": true,
  "accessKeyHint": "4F2A",
  "verifiedAt": "2026-01-15T09:30:00.000Z",
  "lastVerificationError": "Example lastVerificationError",
  "lastVerificationFailedAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes