storage.object.head

Probe object existence + metadata in a customer bucket without fetching the body.

Overview

Property	Value
Workflow type	Atomic
Library	App-storage
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	string	Yes	—	UUID of the organization that owns the connection
storage_connection_uuid	string	Yes	—	UUID of the CloudConnection to use
bucket	string	Yes	—	Bucket to probe
key	string	Yes	—	Object key to probe

Output Schema

Field	Type	Required	Default	Description
organization_uuid	string	Yes	—	UUID of the organization that owns the connection
storage_connection_uuid	string	Yes	—	UUID of the CloudConnection to use
bucket	string	Yes	—	Bucket to probe
key	string	Yes	—	Object key to probe
exists	boolean	No	—	True if the object exists in the bucket
size_bytes	integer	No	—	Object size in bytes; null when exists=False
content_type	string	No	—	MIME type; null when exists=False or not returned
etag	string	No	—	ETag (without quotes); null when exists=False
last_modified	string	No	—	ISO 8601 UTC timestamp; null when exists=False
failure_reason	string	No	—	Engine-stamped human-readable failure reason
failed_at	string	No	—	ISO timestamp when the workflow failed
failed_at_state	string	No	—	Engine-stamped state when the workflow failed
failed_step	string	No	—	Engine-stamped step name (DAG path)
failed_layer	integer	No	—	Engine-stamped layer index (DAG path)
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Probing object in bucket
completed	No	Yes	Yes	—	Object probed
failed	No	Yes	No	—	Probe failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "storage.object.head",
  "initial_data": {
    "organization_uuid": "value",
    "storage_connection_uuid": "value",
    "bucket": "value",
    "key": "value"
  }
}