Skip to main content

Batch operations and SharePoint access

Upload or delete many files in one request, and open Office files for viewing or editing in the browser on SharePoint buckets. Requests use an Authorization: Api-Key TARUVI_API_KEY header.

Batch upload​

Upload up to 100 files in a single multipart request. Total request size is capped at 800 MB.

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/batch-upload/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -F "files=@users/1/avatar.png" \
  -F "files=@users/2/avatar.png" \
  -F 'paths=["users/1/avatar.png","users/2/avatar.png"]'

Response:

{
  "uploaded_count": 2,
  "failed_count": 0,
  "total": 2,
  "successful": [{"index": 0, "path": "users/1/avatar.png", "object": { ... }}],
  "failed": [],
  "message": "Successfully uploaded 2 files"
}

Status codes: 200 OK when every file uploaded, 207 Multi-Status when some files failed. Per-file errors in failed[] include "Permission denied", size or MIME rejections, and provider errors.

Validation rejections — return 400 Bad Request and refuse the whole batch:

  • Total size exceeds 800 MB.
  • Duplicate paths in the request.
  • Any file is empty.
  • paths array length differs from files array length.
  • metadata array (when present) length differs from files.

Each file is checked against the bucket's access policy. Files the caller can't upload appear in failed[] with "Permission denied".

Batch delete​

Delete up to 100 objects in a single request.

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/batch-delete/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"paths":["users/1/avatar.png","users/2/avatar.png"]}'

Response:

{
  "deleted_count": 2,
  "failed": [{"path": "users/3/missing.png", "error": "Object not found"}],
  "message": "Deleted 2 of 3 objects"
}

Status codes: 200 OK when every path was deleted, 207 Multi-Status when some entries failed. Per-object errors include "Object not found" (safe to ignore for idempotent workflows), "Permission denied" (the policy doesn't allow deleting that file), and provider errors.

Duplicate paths are deduplicated automatically. The request rejects with 400 when the paths array is empty, has more than 100 entries, or contains empty strings.

SharePoint view and edit​

These endpoints work only on SharePoint buckets. They give the caller access to the file in SharePoint and return either a link or a redirect to a loading page.

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/OBJECT_PATH/view/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Accept: application/json"

Response:

{"url": "https://<tenant>.sharepoint.com/…", "mode": "view"}

The URL is user-specific and time-bounded by the provider; do not share it across users or embed it as a public asset.

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/OBJECT_PATH/edit/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Accept: application/json"

Edit access requires authentication regardless of visibility. Non-Office MIME types are refused with provider_error_code: "non_office_edit_rejected". The editable Office MIME set is fixed — see Providers for the list.

Redirect flow (browser)​

When the Accept header does not include application/json, the endpoint returns an HTTP redirect to the SharePoint loader page:

curl -sS -D - -o /dev/null "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/OBJECT_PATH/view/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

Response: 302 Found with Location: /sites/{site}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/OBJECT_PATH/open/view/. The loader page provisions the grant and reveals a link once SharePoint propagation completes.

Server-Sent Events grant stream​

The loader page uses a Server-Sent Events endpoint to stream grant progress:

curl -sS -N "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/OBJECT_PATH/open/view/grant/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Accept: text/event-stream"

Events describe each step: inviting the user to SharePoint, granting access, and waiting for access to take effect. TaruviBase waits up to 8 seconds; if it times out, try again.