BigFS API

BigFS stores versioned objects in buckets and can connect buckets to vaults for delivery and processing. This reference is for applications that integrate with api.bigfs.m7.org.

Base URL and request format

The production base URL is https://api.bigfs.m7.org. Every documented route is registered for ANY HTTP method. Send JSON requests with POST unless a route is explicitly described as a binary download, multipart upload, or redirect.

Manage buckets, vaults, stored object versions, remote objects, and task activity in the BigFS application.

curl -sS https://api.bigfs.m7.org/v1/bucket/search \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Successful JSON responses use an envelope with status: 1 and a data value. Some mutation endpoints also return comment. Download and redirect routes return a file stream or an HTTP redirect instead of this envelope.

{
  "status": 1,
  "data": []
}

Validation and other uncaught route errors return HTTP 400 with this JSON envelope. Authorization failures can use 401 or 403 and upload authorization failures also include diagnostic details in data.authorization.

{
  "status": 0,
  "code": 400,
  "comment": "Validation message"
}

Authentication and access

BigFS uses a project-specific authorization contract. Unless a route says otherwise, send an M7 consumer token in the Authorization: Bearer ACCESS_TOKEN header. The token must be issued by id.m7.org for this API. Access is scoped by the principal in the token:

Principal access Supported use
Bucket member Read the bucket and its objects, keys, object relationships, and task records.
Bucket owner or admin Change bucket contents, delete objects and keys, upload data, delete the bucket, and manage bucket members.
Vault member Read a vault.
Vault owner or admin Change or delete the vault, manage its linked buckets, and list its available handlers.
Vault owner Manage vault principals.

Creating a bucket makes the caller its owner. Creating a vault makes the caller its owner; a private handler may only be selected by a root principal. The public redirect route and a one-time download grant are exceptions noted in their route pages.

See Authorization for token acquisition and transport, the upload token-mode exception, offline refresh packages, DPoP status, principal resolution, grant lifetimes, and authorization failures.

Pagination

Access, vault-link, handler-option, and management list endpoints use the same pagination fields:

Field Required Type Behavior
limit No Integer Page size. Defaults to 20; maximum 100.
cursor No String Opaque cursor returned as next_cursor. Takes precedence over offset and page_number.
offset No Integer Zero-based offset.
page_number No Integer One-based page number.

The paged data object contains items, limit, total_count, next_offset, page_number, page_total, and next_cursor. next_cursor is null when there is no next page.

Guides