Buckets and bucket access

Buckets own stored objects. Bucket membership determines who can read a bucket and who can change it. All routes on this page require a consumer token.

Routes

Route	Required fields	Optional fields and behavior
ANY /v1/bucket/search	—	id limits results to one accessible bucket.
ANY /v1/bucket/view	—	id updates an existing bucket; omit it to create one. action: "refresh" returns a record without saving.
ANY /v1/bucket/delete	id	action: "refresh" reports whether the bucket can be deleted.
ANY /v1/bucket/access/add	bucket, principal, role	—
ANY /v1/bucket/access/remove	bucket, principal	—
ANY /v1/bucket/access/search	bucket	role and standard pagination fields.
ANY /v1/bucket/access/update	bucket, principal, role	—
ANY /v1/bucket/access/view	bucket, principal	—
ANY /v1/bucket/vault/search	bucket	Standard pagination fields.

Create or update a bucket

/v1/bucket/view creates a bucket when id is omitted and updates it when id is present. The caller must be a bucket owner or admin to update an existing bucket. The service writes name and meta as supplied; callers should send a non-empty name and a JSON object for meta.

Field	Required	Type	Description
id	No	UUID	Existing bucket ID. Omit to create a bucket.
name	Create/update value	String	Bucket name to store.
meta	No	Object	Bucket metadata to store.
action	No	String	Set to refresh to return a new-record template or an existing bucket without saving.

curl -sS https://api.bigfs.m7.org/v1/bucket/view \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "project-assets",
    "meta": {"environment": "production"}
  }'

{
  "status": 1,
  "data": {
    "id": "BUCKET_UUID",
    "name": "project-assets",
    "meta": {"environment": "production"}
  }
}

/v1/bucket/search returns only buckets to which the caller has membership. When supplied, id is applied only if that bucket is accessible to the caller. Each bucket record contains id, name, meta, created, modified, and expires. meta is returned as a JSON object.

Delete a bucket

Only a bucket owner or admin may use /v1/bucket/delete. Send action: "refresh" first to receive the number of remaining assets. A bucket cannot be deleted while assets remain. Deleting a bucket also removes its memberships and associated task records.

Field	Required	Type	Description
id	Yes	UUID	Bucket to inspect or delete.
action	No	String	refresh reports the remaining asset count instead of deleting.

Manage bucket members

Bucket access records identify a principal and one of these exact roles: owner, admin, member, or viewer.

Route	Caller requirement	Result
/v1/bucket/access/add	Owner or admin	Adds an active principal with the supplied role.
/v1/bucket/access/remove	Owner or admin	Removes a principal's membership.
/v1/bucket/access/search	Owner or admin	Returns matching members in a paged response.
/v1/bucket/access/update	Owner or admin	Changes a member role.
/v1/bucket/access/view	The named principal, owner, or admin	Returns one membership.

Admins cannot create, promote, change, or remove owner or admin members. An owner cannot remove or demote the final remaining owner.

Field	Required	Type	Description
bucket	Yes	UUID	Bucket ID.
principal	Add, remove, update, view	UUID	Principal ID. It must exist and be active for add.
role	Add and update	Enum	owner, admin, member, or viewer. It filters search when supplied.
limit, cursor, offset, page_number	No	Pagination fields	Accepted only by search.

{
  "status": 1,
  "comment": "OK",
  "data": {
    "access": {
      "id": "ACCESS_UUID",
      "principal": "PRINCIPAL_UUID",
      "role": "member"
    },
    "principal": {
      "id": "PRINCIPAL_UUID",
      "name": "Example member",
      "kind": "user"
    }
  }
}

Find vaults linked to a bucket

/v1/bucket/vault/search returns the vaults whose bucket-access list contains the supplied bucket. Any bucket member may call it.

Field	Required	Type	Description
bucket	Yes	UUID	Bucket ID.
limit, cursor, offset, page_number	No	Pagination fields	See the service pagination contract.

Each items entry has vault_access (id, vault, role, timestamps) and a vault summary (id, name).