Remote objects and task queue

Remote-object records and task-queue records are scoped to a bucket. All routes on this page require a consumer token. Read operations require bucket membership; delete and process operations require bucket owner or admin access.

Remote objects

Route	Required fields	Optional fields and behavior
ANY /v1/remote_asset/byasset	asset	—
ANY /v1/remote_asset/view	id	—
ANY /v1/remote_asset/search	bucket	—
ANY /v1/remote_asset/delete	id	vault is accepted but does not select the deletion target.

/v1/remote_asset/byasset returns remote-object records related to one asset. /v1/remote_asset/view returns one remote-object record. /v1/remote_asset/search returns one current resolved asset for each key in the bucket; use it when you need the current assets available in a bucket rather than a filtered relationship lookup.

/v1/remote_asset/delete marks the selected remote object's asset version for deletion and returns an empty data value with the record count in comment. Remote-object records contain id, asset, vault, rid, priority, created, modified, and expires.

Field	Required	Type	Description
asset	byasset	UUID	Asset ID.
id	view, delete	UUID	Remote-object record ID.
bucket	search	UUID	Bucket ID.
vault	No	UUID	Accepted by delete, but does not affect target selection.

Task queue

Route	Required fields	Optional fields and behavior
ANY /v1/task_queue/search	—	id, asset, action, and status filter results; inaccessible records are removed from the result.
ANY /v1/task_queue/view	id	—
ANY /v1/task_queue/byasset	asset	—
ANY /v1/task_queue/process	id, or a filter	process, action, and status.

Read task records

/v1/task_queue/search returns only tasks linked to buckets that the caller can access. Its documented filters are id (UUID), asset (UUID), action, and status (strings). Do not rely on other filter fields. /v1/task_queue/view returns one accessible task. Although its route is named byasset, /v1/task_queue/byasset returns the remote-object records associated with the supplied asset.

Field	Required	Type	Description
id	view	UUID	Task ID.
asset	byasset	UUID	Asset ID.

Task records contain id, bucket, asset, action, workspace, status, priority, retries, note, last_attempt, created, and modified. workspace is returned as a JSON object. The service defines pending and completed task states; integrations must also handle other returned status values.

Process or delete tasks

/v1/task_queue/process runs a single task when id is supplied. Without an id, it considers tasks matching action and status, processes only the records in buckets that the caller owns or administers, and returns one result per processed record.

Field	Required	Type	Description
id	No	UUID	Task to process or delete.
process	No	String	Set to delete to delete instead of executing. Any other value executes.
action	No	String	Filters the batch. any disables this filter.
status	No	String	Filters the batch. any disables this filter.

curl -sS https://api.bigfs.m7.org/v1/task_queue/process \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"id":"TASK_UUID"}'

Successful responses include status: 1, a human-readable comment, and the task processor's result in data.