Agentuity Documentation

Store and manage files and binary objects in buckets.

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

List Objects

List objects in a bucket with optional prefix and pagination.

GET/storage/objects/{bucket}

https://catalyst-usw.agentuity.cloud/storage/objects/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

query

Name	Type	Required	Description
`prefix`	string	No	Only return keys with this prefix
`limit`	number	No	Maximum objects to return
`offset`	number	No	Offset for pagination

Response

Paginated object listing.

Status	Description
200	Object list returned
401	Unauthorized

Response Fields

Field	Type	Description
`objects`	object[]	List of objects
`objects[].bucket_name`	string	The bucket this object belongs to
`objects[].key`	string	Object key (path)
`objects[].size`	number	Object size in bytes
`objects[].etag`	string	Object ETag (optional)
`objects[].content_type`	string	Object content type (optional)
`objects[].last_modified`	string	Last modified timestamp (ISO8601) (optional)
`total`	number	Total count matching the query
`prefix`	string	Prefix filter applied
`limit`	number	Page size
`offset`	number	Page offset

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/storage/objects/my-bucket?prefix=images/&limit=50' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Objects

Delete objects by key or by prefix. key and prefix are mutually exclusive query parameters.

DELETE/storage/objects/{bucket}

https://catalyst-usw.agentuity.cloud/storage/objects/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

query

Name	Type	Required	Description
`key`	string	No	Delete a single object key
`prefix`	string	No	Delete all objects matching prefix

Response

JSON response with deleted object count.

Status	Description
200	Delete operation completed
401	Unauthorized

Response Fields

Field	Type	Description
`deleted_count`	number	Number of objects deleted

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/storage/objects/my-bucket?key=images/photo.jpg' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Generate Presigned URL

Generate a time-limited URL for uploading or downloading an object.

GET/storage/presign/{bucket}

https://catalyst-usw.agentuity.cloud/storage/presign/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

query

Name	Type	Required	Description
`key`	string	Yes	Object key to access
`operation`	string	No	Operation type: `download` or `upload` (default: `download`)

Response

JSON response containing presigned URL and expiry.

Status	Description
200	Presigned URL generated
401	Unauthorized

Response Fields

Field	Type	Description
`presigned_url`	string	The presigned URL
`expiry_seconds`	number	URL expiry time in seconds

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/storage/presign/my-bucket?key=images/photo.jpg&operation=download' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Bucket Stats

Get object count and total size for a bucket.

GET/storage/stats/{bucket}

https://catalyst-usw.agentuity.cloud/storage/stats/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

Response

Bucket-level usage and activity statistics.

Status	Description
200	Bucket stats returned
401	Unauthorized

Response Fields

Field	Type	Description
`bucket_name`	string	The bucket name
`object_count`	number	Number of objects
`total_size`	number	Total size in bytes
`last_event_at`	string	Last event timestamp (ISO8601) (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/storage/stats/my-bucket' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Storage Analytics

Get aggregated analytics across buckets and daily snapshots.

GET/storage/analytics

https://catalyst-usw.agentuity.cloud/storage/analytics

Parameters

query

Name	Type	Required	Description
`days`	number	No	Days of history to include (default: 180)

Response

Analytics summary, per-bucket breakdown, and daily trend data.

Status	Description
200	Analytics returned
401	Unauthorized

Response Fields

Field	Type	Description
`summary`	object	Org-wide totals
`summary.total_object_count`	number	Total objects across all buckets
`summary.total_size`	number	Total size in bytes across all buckets
`summary.estimated_monthly_cost`	number	Estimated monthly cost in USD
`summary.cost_per_gb_month`	number	Cost rate per GB per month in USD
`buckets`	object[]	Per-bucket breakdown
`buckets[].bucket_name`	string	The bucket name
`buckets[].object_count`	number	Number of objects in this bucket
`buckets[].total_size`	number	Total size in bytes for this bucket
`buckets[].last_event_at`	string	Last event timestamp (ISO8601) (optional)
`buckets[].estimated_monthly_cost`	number	Estimated monthly cost for this bucket in USD
`daily`	object[]	Daily snapshots for sparklines
`daily[].date`	string	Snapshot date (YYYY-MM-DD)
`daily[].total_object_count`	number	Total objects on this date
`daily[].total_size`	number	Total size in bytes on this date
`daily[].estimated_cost`	number	Estimated monthly cost at this snapshot in USD
`days`	number	Number of days requested

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/storage/analytics?days=30' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Bucket Config

Retrieve effective configuration for a bucket.

GET/bucket/config/{bucket}

https://catalyst-usw.agentuity.cloud/bucket/config/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

Response

Bucket configuration settings and location metadata.

Status	Description
200	Bucket config returned
401	Unauthorized

Response Fields

Field	Type	Description
`bucket_name`	string	The name of the storage bucket
`storage_tier`	string \| null	Storage tier: `STANDARD`, `INFREQUENT_ACCESS`, or `ARCHIVE` (optional)
`ttl`	number \| null	Object TTL in seconds (optional)
`public`	boolean \| null	Whether the bucket is publicly accessible (optional)
`cache_control`	string \| null	Default Cache-Control header for objects (optional)
`cors`	object \| null	Custom CORS configuration (optional)
`additional_headers`	object \| null	Additional response headers as key-value pairs (optional)
`bucket_location`	string \| null	Bucket location or region override (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/bucket/config/my-bucket' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Bucket Config

Update bucket configuration fields. Omitted fields remain unchanged.

PUT/bucket/config/{bucket}

https://catalyst-usw.agentuity.cloud/bucket/config/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

Request Body

Partial bucket config update payload.

Field	Type	Description
`storage_tier`	string \| null	Storage tier: `STANDARD`, `INFREQUENT_ACCESS`, or `ARCHIVE` (optional)
`ttl`	number \| null	Object TTL in seconds (0 to clear) (optional)
`public`	boolean \| null	Whether the bucket is publicly accessible (optional)
`cache_control`	string \| null	Default Cache-Control header for objects (optional)
`cors`	object \| null	Custom CORS configuration (optional)
`additional_headers`	object \| null	Additional response headers as key-value pairs (optional)

Response

Updated bucket configuration object.

Status	Description
200	Bucket config updated
401	Unauthorized

Response Fields

Field	Type	Description
`bucket_name`	string	The name of the storage bucket
`storage_tier`	string \| null	Storage tier: `STANDARD`, `INFREQUENT_ACCESS`, or `ARCHIVE` (optional)
`ttl`	number \| null	Object TTL in seconds (optional)
`public`	boolean \| null	Whether the bucket is publicly accessible (optional)
`cache_control`	string \| null	Default Cache-Control header for objects (optional)
`cors`	object \| null	Custom CORS configuration (optional)
`additional_headers`	object \| null	Additional response headers as key-value pairs (optional)
`bucket_location`	string \| null	Bucket location or region override (optional)

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/bucket/config/my-bucket' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "ttl": 86400,
  "public": true,
  "cache_control": "max-age=3600"
}'

Delete Bucket Config

Delete custom bucket config and reset to defaults.

DELETE/bucket/config/{bucket}

https://catalyst-usw.agentuity.cloud/bucket/config/{bucket}

Parameters

path

Name	Type	Required	Description
`bucket`	string	Yes	Bucket name

Response

Empty response on success.

Status	Description
200	Bucket config deleted/reset
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/bucket/config/my-bucket' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'