Copy, move or rename a file

Copy, move or rename a file inside Blob Storage with POST /v1/objects/copy, server-side and without downloading it. With move: true the source is removed.

POST /v1/objects/copy

Rename

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
  }'

{
  "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
  }
}

Authorization · 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 an active plan, plus blob:read on the source file.

• The copy keeps the source’s extension, content type, cache, disposition and metadata.
• A copy counts against your storage quota; a move doesn’t.

Parameters

source · string · required

The id of the file to copy.

destination · object · required

Where the copy goes.

Show properties

name · string · required

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

prefix · string

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

private · boolean

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

expire · string | null

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

security_hash · boolean · default: "false"

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

move · boolean · default: "false"

true removes the source after the copy succeeds.

overwrite · 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

status · string

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

response · object

Show properties

id · string

The id of the new file.

private · boolean

Whether the new file is private.

url · string | null

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

expires_at · ISO 8601

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

size · number

The size of the file, in bytes.

source · string

The id of the source.

moved · boolean

Whether the source was removed.

replaced · boolean

Whether an existing file at the destination was replaced.

Rename

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
  }'

{
  "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 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.

Related

• Blob SDK: blob.copy(), blob.move()