Blob Object Copy

POST

objects

copy

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/copy' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "pub/3155597145698959364/uploads/IMG_2041.png",
    "destination": { "name": "cover", "prefix": "posts/launch" },
    "move": true
  }'

const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: 'pub/3155597145698959364/uploads/IMG_2041.png',
    destination: { name: 'cover', prefix: 'posts/launch' },
    move: true,
  }),
});

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/posts/launch/cover.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
    "size": 416230,
    "source": "pub/3155597145698959364/uploads/IMG_2041.png",
    "moved": true,
    "replaced": false
  }
}

string

required

The API key for your account. You can find this in your account settings.

Object Copy duplicates a file under a new name, prefix or visibility, entirely on the server: no bytes go through your application. With move: true the source is removed afterwards, which is how you rename or move a file. Requires the blob:write scope and a paid plan.

The copy keeps the source’s extension, content type, cache, disposition and metadata.
A copy counts against your storage quota; a move doesn’t.
The destination always uses the current storage, so moving is also how you bring a legacy file, stored before the September 2026 update, to the new format (see Object Update).

string

required

The id of the file to copy.

object

required

Where the copy goes.

Show properties

string

required

The new name, without extension. Same pattern as in Object Post.

string

The new prefix. Omit it to store the copy at the root.

boolean

The visibility of the copy. Defaults to the source’s.

string | null

A new expiry counted from now (30d, 6h). null removes it. Omit it to keep the source’s expiry date.

boolean

default:"false"

Adds a random suffix to the new name. Private copies always get it.

boolean

default:"false"

true removes the source after the copy succeeds.

boolean

default:"false"

true replaces an existing file at the destination. Otherwise the request answers 409 OBJECT_ALREADY_EXISTS.

Rate limits

10 requests per 10 seconds (RATE_LIMITED, 429).

Response

string

“success” if successful, “error” if not.

object

Show Toggle object

string

The id of the new file.

boolean

Whether the new file is private.

string | null

The public URL of the new file, or null when private.

ISO 8601

When the new file will be deleted. Present only when it expires.

number

The size of the file, in bytes.

string

The id of the source.

boolean

Whether the source was removed.

boolean

Whether an existing file at the destination was replaced.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/copy' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "pub/3155597145698959364/uploads/IMG_2041.png",
    "destination": { "name": "cover", "prefix": "posts/launch" },
    "move": true
  }'

const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: 'pub/3155597145698959364/uploads/IMG_2041.png',
    destination: { name: 'cover', prefix: 'posts/launch' },
    move: true,
  }),
});

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/posts/launch/cover.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
    "size": 416230,
    "source": "pub/3155597145698959364/uploads/IMG_2041.png",
    "moved": true,
    "replaced": false
  }
}

Errors

Code	HTTP	When
`INVALID_OBJECT`	400	`source` is missing, malformed or not yours.
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	The destination name or prefix doesn’t match the pattern.
`INVALID_DESTINATION`	400	`private` or `security_hash` is not a boolean.
`INVALID_OBJECT_EXPIRE`	400	`expire` is not a duration from 1 hour to 1825 days.
`INVALID_OBJECT_SECURITY_HASH`	400	`security_hash: false` on a private copy.
`SAME_OBJECT`	400	The destination is the source.
`PERMISSION_DENIED`	401	The account has no active paid plan.
`UPGRADE_REQUIRED`	403	The expiry needs a higher plan.
`STORAGE_QUOTA_EXCEEDED`	403	The copy would pass the included storage.
`OBJECT_NOT_FOUND`	404	The source doesn’t exist.
`OBJECT_ALREADY_EXISTS`	409	A file exists at the destination and `overwrite` is not `true`.
`RATE_LIMITED`	429	More than 10 requests in 10 seconds.
`COPY_FAILED`	500	The copy failed. Retry.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Storage is temporarily unavailable. Retry.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/copy' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "pub/3155597145698959364/uploads/IMG_2041.png",
    "destination": { "name": "cover", "prefix": "posts/launch" },
    "move": true
  }'

const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: 'pub/3155597145698959364/uploads/IMG_2041.png',
    destination: { name: 'cover', prefix: 'posts/launch' },
    move: true,
  }),
});

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/posts/launch/cover.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
    "size": 416230,
    "source": "pub/3155597145698959364/uploads/IMG_2041.png",
    "moved": true,
    "replaced": false
  }
}

Getting Started

Objects

Chunked Uploads

Account

Share Links

S3

Rate limits

Response

Errors

​Rate limits

​Response

​Errors

Rate limits

Response

Errors