Skip to main content

Find, browse, copy, and move objects

Find and rearrange files: list with filters, browse as folders, search, and copy or move. Requests go to TARUVI_SITE_URL/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/ with an Authorization: Api-Key TARUVI_API_KEY header.

List and filter​

The list endpoint accepts a rich filter grammar. Every parameter is optional.

Return only PDFs in a folder, largest first:

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/?prefix=reports/&mimetype=application/pdf&ordering=-size&page_size=50" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

Return objects the caller created since a date:

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/?created_by_me=true&created_after=2026-09-01" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

Search filename or path substring:

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/?search=invoice" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

Combine visibility with pagination:

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/?visibility=public&page=2&page_size=50&ordering=-created_at" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

The full filter grammar — range filters, MIME categories, path lookups, tags, ordering — is on the Filter grammar reference.

Browse as folders​

GET /objects/browse/ treats paths as folders and returns one level at a time. It requires sign-in, even for public buckets.

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/browse/?prefix=documents/2024/&sort=name&order=asc&page=1&page_size=50" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

Response body:

{
  "prefix": "documents/2024/",
  "folders": [{ "type": "folder", "name": "Q1", "path": "documents/2024/Q1/" }],
  "objects": [{
    "type": "file", "id": 1, "uuid": "…", "name": "report.pdf",
    "path": "documents/2024/report.pdf", "size": 12345, "mimetype": "application/pdf",
    "visibility": "private", "is_office_editable": false,
    "created_at": "…", "updated_at": "…", "download_url": "…"
  }],
  "page": 1, "page_size": 50, "has_next": false
}

Navigate deeper by passing a folder's path back as prefix. Sort field is one of name, size, created_at, updated_at; order is asc or desc. page_size is bounded at 100.

POST /objects/search/ accepts a JSON body for structured filtering with a bounded result limit.

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/search/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"users/123/","search":"profile","sortBy":{"column":"created_at","order":"desc"},"limit":100,"offset":0}'

limit defaults to 100 and is capped at 1000. sortBy.column is one of filename, size, created_at, updated_at, path, mimetype; any other value falls back to created_at. The response envelope contains objects (the list) and bucket (the slug); total rides on the envelope.

Copy an object​

Copy leaves the source in place and creates a new object at the destination. Same-app operation — the destination bucket must live under the same app_slug as the source.

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/copy/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"source_path":"users/user-123/avatar.png","destination_bucket":"user-thumbnails","destination_path":"users/user-123/avatar.png"}'

destination_bucket is optional and defaults to the current bucket. Copy returns 201 Created. The caller needs read access to the source and upload access to the destination.

Move or rename​

Move rewrites the object. Same-bucket moves become a path rename; cross-bucket moves copy then delete.

Rename in place:

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/move/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"source_path":"temp/upload-1234.pdf","destination_path":"invoices/2024/Q3/INV-1234.pdf"}'

Move to a different bucket in the same app:

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/objects/move/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"source_path":"drafts/report.docx","destination_bucket":"published-reports","destination_path":"2024/Q3/report.docx"}'

Move failure modes:

  • 409 Conflict — destination path is occupied. Rename the source or clear the destination first.
  • 400 with "Cross-provider move is not supported" — source and destination buckets use different storage_provider values. Download the object, upload it to the target bucket, and delete the source separately.
  • 404 with "Source object 'PATH' not found" — the source_path does not match any object in the resolved source bucket.

Moving within a bucket needs update access. Moving to another bucket needs delete access on the source and upload access on the destination.