For AI agents: markdown of this page — /docs-content-en/storage/upload/presigned.md documentation index — /llms.txt

Create presigned URL

POST /v1/storage/objects

Temporarily disabled. This fail-closed method returns 503 STORAGE_PRESIGNED_UPLOAD_DISABLED. Use direct upload or multipart upload.

Path B does not replace or revive soft-deleted objects. While it is disabled, every request returns 503 STORAGE_PRESIGNED_UPLOAD_DISABLED before a URL is minted. If occupied-key handling becomes reachable again, a deleted object will still return 409 STORAGE_KEY_DELETED without an uploadUrl. New bytes can be written into an eligible deleted row by direct upload (Path A), or for a personal key after explicit DELETE, by multipart upload (Path C).

The first step of uploading a file from 10 MB to 5 GB — returns a temporary URL the client uses to send the file directly via PUT; after sending, you call upload completion.

Request fields (body)

Field Type Required Default Description
key string yes — Logical object key: from 1 to 1024 characters, allowed a-z, A-Z, 0-9, ., _, /, -; must not start with / or ., must not contain ..
contentType string yes — File MIME type; must match the Content-Type header on the PUT request to uploadUrl
visibility string no PRIVATE Object visibility: PRIVATE or PUBLIC
sizeBytes number no — Expected file size in bytes; an optional hint, the actual size is captured at the completion step
ttlSeconds number no 3600 Presigned URL lifetime in seconds: from 60 to 86400

Examples

curl — personal key

Terminal 
# Step 1 — get a presigned URL
curl -X POST https://vibecode.bitrix24.com/v1/storage/objects \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "users/42/report.pdf",
    "contentType": "application/pdf",
    "visibility": "PRIVATE"
  }'

# Step 2 — send the file to the received uploadUrl
curl -X PUT "https://storage.example.com/upload/..." \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl — OAuth application

Terminal 
# Step 1 — get a presigned URL
curl -X POST https://vibecode.bitrix24.com/v1/storage/objects \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "users/42/report.pdf",
    "contentType": "application/pdf",
    "visibility": "PRIVATE"
  }'

# Step 2 — send the file to the received uploadUrl
curl -X PUT "https://storage.example.com/upload/..." \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

JavaScript — personal key

javascript 
// Step 1 — get a presigned URL
const res = await fetch('https://vibecode.bitrix24.com/v1/storage/objects', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'users/42/report.pdf',
    contentType: 'application/pdf',
    visibility: 'PRIVATE',
  }),
})
if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
  return
}
const result = await res.json()

// Step 2 — send the file to the presigned URL
const put = await fetch(result.uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: file, // File or Blob
})
if (!put.ok) throw new Error(`PUT failed: ${put.status}`)

JavaScript — OAuth application

javascript 
// Step 1 — get a presigned URL
const res = await fetch('https://vibecode.bitrix24.com/v1/storage/objects', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'users/42/report.pdf',
    contentType: 'application/pdf',
    visibility: 'PRIVATE',
  }),
})
const result = await res.json()

// Step 2 — send the file to the presigned URL
await fetch(result.uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: file, // File or Blob
})

Response fields

Field Type Description
objectId string Object identifier; pass it to POST /v1/storage/objects/complete
uploadUrl string Presigned URL for sending the file via the PUT method
bucket string Internal container name
objectKey string Internal object key in storage
expiresAt string Presigned URL expiry (ISO 8601), taken from the URL signature. May come earlier than the requested ttlSeconds

Response example

JSON 
{
  "objectId": "cmpf9b1gp003omr0zkc0qjojn",
  "uploadUrl": "https://storage.example.com/upload/portals/example-portal/users/42/report.pdf?X-Amz-Signature=abc123",
  "bucket": "example-storage-bucket",
  "objectKey": "portals/example-portal/users/42/report.pdf",
  "expiresAt": "2026-05-21T09:57:43.675Z"
}

Error response example

400 — ttlSeconds is outside the allowed range:

JSON 
{
  "success": false,
  "error": {
    "code": "STORAGE_INVALID_TTL",
    "message": "ttlSeconds must be between 60 and 86400"
  }
}

Errors

HTTP Code Description
403 STORAGE_SCOPE_REQUIRED The API key lacks the vibe:storage scope
409 STORAGE_KEY_EXISTS An object under this key already exists. Replacing content through a presigned URL is not supported — use a direct upload
409 STORAGE_KEY_DELETED Path B does not revive a deleted object: the key stays occupied until purge and no uploadUrl is minted. While Path B is disabled, 503 STORAGE_PRESIGNED_UPLOAD_DISABLED is returned before this refusal
409 STORAGE_MULTIPART_IN_PROGRESS A multipart upload is in progress for this key — complete or abort it
409 STORAGE_KEY_OWNED_ELSEWHERE The name belongs to an object of the other ownership kind (app-shared vs per-employee)
409 STORAGE_KEY_CONFLICT The reservation changed while the URL was being minted — retry
400 STORAGE_VISIBILITY_MISMATCH Re-minting a URL for your own unfinished reservation cannot change its visibility — omit visibility or pass the current value
401 STORAGE_NO_AUTH_CONTEXT The request was made without authorization
400 STORAGE_KEY_REQUIRED The key field was not provided
400 STORAGE_CONTENT_TYPE_REQUIRED The contentType field was not provided
400 STORAGE_INVALID_KEY The key value violates the format rules
400 STORAGE_INVALID_VISIBILITY Invalid visibility value
400 STORAGE_INVALID_SIZE Invalid sizeBytes value
400 STORAGE_INVALID_TTL ttlSeconds is outside the range 60–86400
402 BILLING_INSUFFICIENT Insufficient balance
503 STORAGE_FEATURE_DISABLED Storage is disabled for the portal
503 STORAGE_PRESIGNED_UPLOAD_DISABLED Path B is temporarily disabled; use Path A or C
503 STORAGE_STS_UNAVAILABLE The temporary credentials issuance service is unavailable
502 STORAGE_BUCKET_ERROR Error while interacting with storage

Full list of common API errors — Errors.

Known specifics

Mandatory second step. After sending the file to uploadUrl you must call upload completion with the objectId from this response. Until completion, the object stays in PENDING status and cannot be downloaded.

URL lifetime. ttlSeconds limits the lifetime of the presigned upload URL, not the retention period of the finished object. It is the requested lifetime: the effective one is returned in expiresAt and may be shorter. Schedule the file upload by expiresAt, not by ttlSeconds, and upload as early as you can.

See also