Skip to main content
PUT
/
pictoryapis
/
v1
/
awsconnections
/
{connectionid}
Update AWS Private Connection
curl --request PUT \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "enabled": true,
  "version": 123
}
'
{
  "enabled": true,
  "name": "UpdatedConnectionName",
  "description": "Updated connection description",
  "awsAccountId": "123456789012",
  "awsRegion": "us-east-2",
  "connectionId": "20251217080657842fux3au9kh1p0j5s",
  "version": 2
}

Documentation Index

Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This endpoint allows you to update an existing AWS S3 private connection. You can modify the connection name, description, or enable/disable the connection without changing the AWS account ID or region.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.
Important: You cannot change the AWS Account ID or AWS Region of an existing connection. If you need to change these values, create a new connection instead.

​
Use Cases

Rename Connection

Update the connection name for better organization

Update Description

Modify the description to reflect usage changes

Enable/Disable

Temporarily disable a connection without deleting it

Manage Settings

Update connection settings as your needs change

​
API Endpoint

PUT https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}

​
Request Parameters

​
Path Parameters

​
connectionid
string
required
The unique identifier of the AWS connection you want to update. This is the connectionId value returned when you created the connection.
Example: 20251217080657842fux3au9kh1p0j5s

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY
Get your API key from the API Access page in your Pictory dashboard.
​
Content-Type
string
required
Must be set to application/json

​
Body Parameters

Do NOT include awsRegion or awsAccountId in the request body. These fields are immutable and including them will cause errors.
​
name
string
required
Updated name for the AWS connectionExample: "UpdatedConnectionName"
​
description
string
Updated description of the AWS connectionExample: "Updated connection description"
​
enabled
boolean
Whether the connection should be active (true) or disabled (false). If not provided, the existing value is preserved.Example: true
​
version
integer
required
The current version number of the connection (for optimistic locking). This prevents concurrent updates from overwriting each other. Get the current version from the Get Connection by ID endpoint.Example: 1

​
Response

Returns the updated AWS connection object. The version number is incremented with each successful update. Note that awsAccountId, awsRegion, and connectionId cannot be changed.

​
Response Examples

{
  "enabled": true,
  "name": "UpdatedConnectionName",
  "description": "Updated connection description",
  "awsAccountId": "123456789012",
  "awsRegion": "us-east-2",
  "connectionId": "20251217080657842fux3au9kh1p0j5s",
  "version": 2
}

​
Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_Replace YOUR_CONNECTION_ID with the actual connection ID you want to update
# Update an AWS connection
# Replace YOUR_API_KEY with your actual API key
# Replace YOUR_CONNECTION_ID with your connection ID

curl --request PUT \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections/YOUR_CONNECTION_ID \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "UpdatedConnectionName",
    "description": "Updated connection description",
    "enabled": true,
    "version": 1
  }' | python -m json.tool

​
Common Use Cases

​
Rename a Connection

// Update connection name for better organization
// First, get the current connection to retrieve the version
const connection = await getAwsConnectionById(apiKey, connectionId);

const updates = {
  name: 'Production-S3-Connection',
  description: 'Production environment AWS S3 assets',
  enabled: true,
  version: connection.version
};

const result = await updateAwsConnection(apiKey, connectionId, updates);
console.log(`Connection renamed to: ${result.name}`);

​
Temporarily Disable a Connection

# Disable connection without deleting it
# First, get the current connection to retrieve the version
connection = get_aws_connection_by_id(api_key, connection_id)

updates = {
    "name": "PictoryPrivateVideosConnection",
    "description": "Pictory Private Videos Connection",
    "enabled": False,  # Disable the connection
    "version": connection["version"]
}

result = update_aws_connection(api_key, connection_id, updates)
print(f"Connection is now {'enabled' if result['enabled'] else 'disabled'}")

​
Re-enable a Disabled Connection

// Re-enable a previously disabled connection
// First, get the current connection to retrieve the version
const connection = await getAwsConnectionById(apiKey, connectionId);

const updates = {
  name: 'PictoryPrivateVideosConnection',
  description: 'Pictory Private Videos Connection',
  enabled: true,  // Re-enable the connection
  version: connection.version
};

const result = await updateAwsConnection(apiKey, connectionId, updates);
console.log('Connection re-enabled successfully');

​
Update Description Only

# Update just the description, keep other fields unchanged
# First get the current connection details
current = get_aws_connection_by_id(api_key, connection_id)

# Update with new description
updates = {
    "name": current["name"],  # Keep existing name
    "description": "Updated description with new information",
    "enabled": current["enabled"],  # Keep existing enabled state
    "version": current["version"]  # Include current version for optimistic locking
}

result = update_aws_connection(api_key, connection_id, updates)
print(f"Description updated: {result['description']}")

​
Error Handling

Cause: The connection ID does not exist or has been deletedSolution:
  • Verify the connection ID is correct
  • Use the Get AWS Connections endpoint to list all available connections
  • Check if the connection was deleted
Cause: Invalid or missing API keySolution:
  • Verify your API key is correct and starts with pictai_
  • Check the Authorization header is properly formatted: YOUR_API_KEY
  • Ensure your API key hasn’t expired
  • Get a new API key from the API Access page
Cause: Required fields are missing from the request bodySolution:
  • Ensure both name and version fields are included
  • Verify the request body is valid JSON
  • The enabled field is optional - if omitted, the existing value is preserved
Cause: Field values do not meet validation requirementsSolution:
  • name must be a non-empty string (required)
  • version must be a positive integer (required)
  • enabled must be a boolean value (true or false) if provided (optional)
  • description should be a string if provided (optional)
  • Do NOT include awsRegion or awsAccountId in the request - these fields cannot be changed
Cause: The version number you provided does not match the current version (someone else updated the connection)Solution:
  • Get the latest connection details using the Get Connection by ID endpoint
  • Use the current version number from that response
  • Retry your update request with the new version number
This is called “optimistic locking” and prevents concurrent updates from overwriting each other.
Cause: You do not have permission to update this connectionSolution:
  • Verify the connection belongs to your account
  • Check that your API key has the necessary permissions
  • Contact support if you believe you should have access

​
Important Notes

Cannot Change AWS CredentialsYou cannot update the awsAccountId or awsRegion of an existing connection. These values are set when the connection is created and cannot be modified. Do NOT include these fields in your update request.What happens if you try:
  • Including awsRegion in the request body will cause a 400 Bad Request error
  • Including awsAccountId in the request body will cause a 400 Bad Request error
  • The connectionId is in the URL path and cannot be changed
If you need to change AWS Account ID or Region:
  1. Create a new connection with the correct values using Create AWS Connection
  2. Update your video creation workflows to use the new connection ID
  3. Delete the old connection using Delete AWS Connection
Version TrackingEach successful update increments the version number of the connection. This helps track configuration changes over time.
Disabling vs DeletingInstead of deleting a connection you may need later, consider temporarily disabling it by setting enabled: false. This preserves the configuration while preventing its use in video creation.

​
Next Steps

List All Connections

Retrieve all your AWS S3 private connections

Get Connection Details

Get details of a specific connection before updating

Get API Key

Access your API key from your Pictory dashboard

Delete Connection

Permanently delete an AWS connection