Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ub.bitbros.in/llms.txt

Use this file to discover all available pages before exploring further.

urBackend handles file and image uploads for you. Upload a file and receive a public CDN URL you can use directly in your application. Base URL: https://api.ub.bitbros.in
All storage endpoints require your secret key (sk_live_...) in the x-api-key header. These operations should only be performed server-side.
All uploaded files are publicly accessible via the returned URL. Do not upload sensitive or private documents.

​
Upload a file

Uploads use a presigned URL three-step flow so the binary is sent directly to storage.

​
Step 1 — Request an upload URL

Endpoint: POST /api/storage/upload-request Request body (size in bytes): 
{
  "filename": "avatar.png",
  "contentType": "image/png",
  "size": 123456
}
Response: 
{
  "signedUrl": "https://storage.example.com/...",
  "token": "optional-provider-token",
  "filePath": "PROJECT_ID/550e8400-e29b-41d4-a716-446655440000_avatar.png"
}
FieldDescription
signedUrlPresigned URL to upload the binary directly to storage
tokenProvider-specific token (only returned for some external providers)
filePathOpaque storage path (format: projectId/uuid_sanitizedFilename) — save this to confirm or delete the file later
This endpoint enforces the 10 MB max file size and checks available headroom against your plan’s project storage quota before the upload is confirmed. On the free tier, the default project storage limit is 20 MB.

​
Step 2 — Upload the binary to storage

Send a browser PUT request to signedUrl with the raw file contents and the correct Content-Type header. 
const uploadRes = await fetch(signedUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': file.type
  },
  body: file
});

if (!uploadRes.ok) {
  throw new Error(`Upload failed: ${uploadRes.status} ${uploadRes.statusText}`);
}

​
Step 3 — Confirm the upload

Endpoint: POST /api/storage/upload-confirm Request body: 
{
  "filePath": "PROJECT_ID/550e8400-e29b-41d4-a716-446655440000_avatar.png",
  "size": 123456
}
Response: 
{
  "message": "Upload confirmed",
  "path": "PROJECT_ID/550e8400-e29b-41d4-a716-446655440000_avatar.png",
  "provider": "internal",
  "url": "https://xyz.supabase.co/storage/v1/object/public/dev-files/PROJECT_ID/550e8400-e29b-41d4-a716-446655440000_avatar.png"
}
FieldDescription
messageConfirmation message
pathNormalized storage path — use this to delete the file later
providerStorage backend used (internal or external)
urlPublic URL for the file. If unavailable, this is null.
warningOptional warning message when a public URL is unavailable
If the storage provider does not expose a public URL (for example, some external S3/R2 setups), the response returns url: null and includes a warning field explaining that a public URL is not available.
The confirm step verifies the object exists, checks the size matches, and then charges quota atomically.

​
Full browser example

if (!fileInput?.files?.length) {
  throw new Error('No file selected');
}

const file = fileInput.files[0];

const requestRes = await fetch('https://api.ub.bitbros.in/api/storage/upload-request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_YOUR_KEY'
  },
  body: JSON.stringify({
    filename: file.name,
    contentType: file.type,
    size: file.size
  })
});

if (!requestRes.ok) {
  const errorBody = await requestRes.json().catch(() => null);
  throw new Error(
    `Upload request failed: ${requestRes.status} ${requestRes.statusText}${
      errorBody?.error ? ` - ${errorBody.error}` : errorBody?.message ? ` - ${errorBody.message}` : ''
    }`
  );
}

const { signedUrl, filePath } = await requestRes.json();

const uploadRes = await fetch(signedUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file
});

if (!uploadRes.ok) {
  throw new Error(`Upload failed: ${uploadRes.status} ${uploadRes.statusText}`);
}

const confirmRes = await fetch('https://api.ub.bitbros.in/api/storage/upload-confirm', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_YOUR_KEY'
  },
  body: JSON.stringify({ filePath, size: file.size })
});

if (!confirmRes.ok) {
  if (confirmRes.status === 409) {
    const retryableError = await confirmRes.json();
    throw new Error(
      `Upload not ready yet: ${retryableError.error || retryableError.code || 'UPLOAD_NOT_READY'}. Retry the confirm request shortly.`
    );
  }

  const errorBody = await confirmRes.json().catch(() => null);
  throw new Error(
    `Upload confirm failed: ${confirmRes.status} ${confirmRes.statusText}${
      errorBody?.error ? ` - ${errorBody.error}` : errorBody?.message ? ` - ${errorBody.message}` : ''
    }`
  );
}

const { url, provider, path, warning } = await confirmRes.json();
console.log(url, provider, path, warning);
SDK users (urbackend-sdk) do not need to change anything — client.storage.upload() uses this flow internally.

​
Required bucket CORS (S3/R2)

If you use AWS S3 or Cloudflare R2 with presigned browser uploads, configure bucket CORS so browser uploads to signedUrl can pass preflight. Required methods:
  • PUT
  • OPTIONS
  • GET
  • HEAD
Required AllowedHeaders (not ExposeHeaders) should include at least:
  • content-type — required for presigned PUT requests
  • content-length — typically safelisted, but some providers still require it to be allow-listed
Without these CORS rules, browser uploads can fail even when POST /api/storage/upload-request and POST /api/storage/upload-confirm are correct.

​
Delete a file

To delete a file, pass the path returned from the upload response. Endpoint: DELETE /api/storage/file 
await fetch('https://api.ub.bitbros.in/api/storage/file', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_YOUR_KEY'
  },
  body: JSON.stringify({
    path: 'YOUR_PROJECT_ID/your_file_name.png'
  })
});
If the path is invalid or the file has already been removed, the API returns 404.

​
Limits

LimitValue
Maximum file size10 MB per file
Total storage per project20 MB (free tier; higher limits on paid plans)

​
Troubleshooting

Ensure filename, contentType, and size are provided for the upload request, and that filePath and size are sent to the confirm endpoint.
The x-api-key header is missing or contains an invalid key. Check that you are using a valid key from your project dashboard.
The file exceeds the 10 MB per-file limit. Compress or resize the file before uploading.
If you use an external S3/R2 bucket, configure bucket CORS to allow PUT, OPTIONS, GET, and HEAD, and allow content-type and content-length headers from your client origin.