Storage destinations API

Configure where HCTI saves rendered files. Your bucket must already exist, and your plan must support storage destinations. Compare plans to add this feature. See the storage guide for provider permissions and image storage behavior.

Reads, including the AWS external-ID operation, share 100 requests/minute. Writes share 20 requests/minute, per organization across REST and MCP. See rate limits and the interactive API reference.

First retrieve your organization’s external ID and HCTI’s writer role ARN:

curl 'https://hcti.io/v1/storage-destinations/aws-external-id' \
  --user "$HCTI_API_ID:$HCTI_API_KEY"

The response contains both values needed to construct the IAM role trust policy:

This operation requires storage_destinations:create_update and does not require a destination ID.

Create a role in your AWS account that allows sts:AssumeRole by the returned writer_role_arn, with a StringEquals condition requiring the returned external_id as sts:ExternalId. See the Amazon S3 guide. Attach the role’s bucket permissions, then create the destination using your newly created role’s ARN as connection_info.role_arn, not HCTI’s writer_role_arn:

curl 'https://hcti.io/v1/storage-destinations' \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Production images",
    "disabled": false,
    "hcti_storage_disabled": false,
    "connection_info": {
      "provider": "aws_s3",
      "bucket": "your-image-bucket",
      "key_prefix": "renders/",
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::123456789012:role/HctiImageStorage"
    }
  }'

Replace the example bucket and role with your configured AWS resources. HCTI tests a write before enabling the destination.

All providers require bucket. All except Amazon S3 use access_key_id and secret_access_key; Amazon S3 uses an IAM role instead. On update, access-key providers can use retain_secret_access_key: true to keep the existing secret explicitly.

Use a provider’s supported region value from the API reference. Custom endpoints must not contain a path, query, fragment, or credentials. Do not send a generic custom endpoint in place of the provider-specific fields.

Creates, updates, and gets return 200 OK with:

• List destinations: GET /v1/storage-destinations returns destinations newest first, including disabled destinations.
• Page size: Set count from 1 to 100. The default is 10.
• Next page: Pass the response’s pagination.next_page_start as page_start in the next request. Stop when the returned cursor is null.
• Retrieve one destination: Use GET /v1/storage-destinations/{id}.

See pagination for the shared response format.

Send POST /v1/storage-destinations/{id} with the complete replacement configuration. Omitted optional settings clear or reset. For access-key providers, choose explicitly whether to retain or replace the secret:

• Keep the secret: Set connection_info.retain_secret_access_key: true, keep the provider and access key ID unchanged, and omit secret_access_key or set it to null. Existing credentials are required.
• Replace the secret: Supply connection_info.secret_access_key and omit retain_secret_access_key or set it to false. Creating a destination or changing its provider or access key ID requires a supplied secret.
• Missing or conflicting instructions: An omitted, null, or false retention flag requires a supplied secret, including when disabling the destination. Combining retain_secret_access_key: true with a supplied secret returns 400. Empty or whitespace-only storage secrets are invalid.

For example, this complete R2 update retains the existing secret. Replace the destination ID, account ID, access key ID, and other settings with those of your destination:

curl "https://hcti.io/v1/storage-destinations/$DESTINATION_ID" \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Production images",
    "disabled": false,
    "hcti_storage_disabled": false,
    "connection_info": {
      "provider": "cloudflare_r2",
      "bucket": "your-image-bucket",
      "key_prefix": "renders/",
      "cloudflare_account_id": "0123456789abcdef0123456789abcdef",
      "access_key_id": "your-existing-access-key-id",
      "retain_secret_access_key": true
    }
  }'

Amazon S3 uses an IAM role, so these access-key retention fields do not apply. Retention flags are request-only and are not returned in connection_info.

Creation tests a write to the bucket. Changed connection settings and re-enabling a destination also trigger testing; metadata-only changes do not require a test. HCTI attempts to delete its test object, but cleanup failure does not make the write test fail. Test objects may remain under <key-prefix>/.hcti/connection-tests/ without delete permission.

An enabled request is not saved if the test fails. An explicitly disabled configuration can be saved with a failed test result. Inspect last_test_succeeded and last_test_error; a successful write test does not verify read permissions or guarantee future connectivity.

After a plan downgrade removes storage-destination support, updates can only disable the destination; other submitted changes are ignored.

DELETE /v1/storage-destinations/{id} returns 204 No Content on success. Repeated deletion succeeds. It removes the configuration and its stored credentials, but does not delete the bucket or objects already stored there. Existing images retain their destination reference, and storage retries depending on a disabled or deleted destination fail.

Pass the returned id as storage_destination_id on an image request or template. Creating an image uses image permissions; managing destination configuration uses the permissions above. Authenticated PUT /v1/store/{id} requires images:store.

Create accepts content with the request fields above. Update takes id and content; get/delete take id; list takes count and page_start. get_aws_storage_external_id takes no arguments.

For example: “Use HCTI to get my AWS storage external ID so I can configure an IAM role, then list my storage destinations.” Approve both storage_destinations:create_update and storage_destinations:read for that workflow. See MCP tools and authorization.