Objects, keys, and uploads
An object is a stored version associated with a key in a bucket. All routes on this page require a consumer token, except upload routes, which accept a valid M7 token whose principal has the required bucket access.
Routes
| Route | Required fields | Optional fields and behavior |
|---|---|---|
ANY /v1/key/search |
bucket |
— |
ANY /v1/key/bykey |
bucket, key |
— |
ANY /v1/key/view |
bucket when creating; id when updating |
action: "refresh" returns a record without saving. |
ANY /v1/key/delete |
id, or bucket and name/key |
version selects a version. |
ANY /v1/key/cleanup |
bucket |
id and version are accepted in the cleanup report. |
ANY /v1/asset/search |
bucket |
— |
ANY /v1/asset/bykey |
bucket, key |
— |
ANY /v1/asset/view |
key when creating; id when updating |
version, meta, status_reset, and action. |
ANY /v1/asset/delete |
id, or key |
version limits the delete operation. |
ANY /v1/upload/form_data |
bucket, multipart files |
names overrides uploaded filenames by file index. |
ANY /v1/upload/post_data |
X-Bucket header or bucket |
X-Object-Name selects the object key. |
Keys
/v1/key/search lists the keys in a bucket, and /v1/key/bykey lists all
asset versions for a named key. A bucket member may read either route. Key
mutation and cleanup require bucket owner or admin access.
Key records contain id, bucket, key, created, modified, and expires.
The value in key is the stored key name.
Save a key
Use /v1/key/view without id to create a key. Use it with id to update
the stored key name. The action: "refresh" variant returns a blank template
when id is omitted, or the existing record when it is supplied.
| Field | Required | Type | Description |
|---|---|---|---|
id |
No | UUID | Existing key ID for update or refresh. |
bucket |
Create | UUID | Parent bucket ID. |
name |
Create/update value | String | Key name to store. |
action |
No | String | refresh skips saving. |
curl -sS https://api.bigfs.m7.org/v1/key/view \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"bucket":"BUCKET_UUID","name":"reports/january.pdf"}'
The success data contains record (the key with id, bucket, key,
and timestamps) and last, an array of service log entries.
Delete or clean up a key
/v1/key/delete marks the selected asset records for deletion; it does not
delete a key record directly. Select the key by id, or by bucket plus
name. key is an alias for name. If version is omitted or not a
positive integer, all applicable versions are selected.
/v1/key/cleanup requires bucket and runs cleanup for that bucket. It also
accepts id and version in the request, but the cleanup target is the
specified bucket.
Assets
Assets are individual stored versions under a key. A bucket member may list them; owner or admin access is required to save, refresh, or mark them for deletion.
Asset records contain id, key, meta, content_hash, version, status,
size, created, modified, and expires. meta is returned as a JSON
object. Asset statuses are processing, deleted, active, locked, or
pending.
| Route | Request fields | Success data |
|---|---|---|
/v1/asset/search |
bucket |
One current resolved asset for each key in the bucket. |
/v1/asset/bykey |
bucket, key |
Array of all versions for the key. |
/v1/asset/view |
See below. | Saved or refreshed asset record. |
/v1/asset/delete |
id, or key; optional version. |
Empty data with a count in comment. |
Save an asset record
Use /v1/asset/view without id to create an asset record. Creating requires
key; version is applied only when it is a positive integer. The meta
value may be a JSON object or JSON object string; an omitted or empty value is
stored as {}. Set status_reset to 1 to set the status to active.
| Field | Required | Type | Description |
|---|---|---|---|
id |
No | UUID | Existing asset ID for update or refresh. |
key |
Create | UUID | Parent key ID. Also identifies an asset for refresh when id is omitted. |
version |
No | Integer | Version set on creation when positive. |
meta |
No | Object or JSON object string | Metadata to store. |
status_reset |
No | Integer | Set to 1 to reset status to active. |
action |
No | String | refresh returns a new-record template or existing record without saving. |
For /v1/asset/delete, id selects one asset. Otherwise key selects the
key and optional version narrows the operation. bucket is accepted by the
route but does not select the deletion target.
Upload data
Multipart upload
/v1/upload/form_data accepts only POST. The caller must be a bucket owner
or admin. Send bucket and one or more files in the multipart field files.
Use names as an array keyed by file index to override source filenames.
curl -sS https://api.bigfs.m7.org/v1/upload/form_data \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-F 'bucket=BUCKET_UUID' \
-F 'files[]=@./report.pdf' \
-F 'names[0]=reports/latest.pdf'
The response data is an array of { "file": "…", "status": "uploaded:…" }
or per-file error entries. Overall status is 0 when one or more files fail.
Raw upload
/v1/upload/post_data accepts POST or PUT with a non-empty raw request
body. Send X-Bucket: BUCKET_UUID; bucket in the request is a fallback.
Set X-Object-Name to select the key name. If it is omitted, the trailing
route path is used when available. The caller must be a bucket owner or admin.
curl -sS --request PUT https://api.bigfs.m7.org/v1/upload/post_data \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'X-Bucket: BUCKET_UUID' \
-H 'X-Object-Name: reports/latest.txt' \
--data-binary @./latest.txt
The result has data.file and data.status. An empty body, missing bucket,
or unsupported method is rejected.