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
}
'import requests
url = "https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}"
payload = {
"name": "<string>",
"description": "<string>",
"enabled": True,
"version": 123
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
body: JSON.stringify({name: '<string>', description: '<string>', enabled: true, version: 123})
};
fetch('https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'enabled' => true,
'version' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"version\": 123\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"version\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"version\": 123\n}"
response = http.request(request)
puts response.read_body{
"enabled": true,
"name": "UpdatedConnectionName",
"description": "Updated connection description",
"awsAccountId": "123456789012",
"awsRegion": "us-east-2",
"connectionId": "20251217080657842fux3au9kh1p0j5s",
"version": 2
}
{
"code": "INVALID_REQUEST_BODY",
"message": "Request body validation failed.",
"fields": [
{
"name": "enabled",
"errors": "enabled is required"
}
]
}
{
"message": "Unauthorized"
}
{
"message": "Connection not found"
}
AWS Integration
Update AWS Private Connection
Modify an existing AWS S3 private connection configuration
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
}
'import requests
url = "https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}"
payload = {
"name": "<string>",
"description": "<string>",
"enabled": True,
"version": 123
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
body: JSON.stringify({name: '<string>', description: '<string>', enabled: true, version: 123})
};
fetch('https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'enabled' => true,
'version' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"version\": 123\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"version\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"version\": 123\n}"
response = http.request(request)
puts response.read_body{
"enabled": true,
"name": "UpdatedConnectionName",
"description": "Updated connection description",
"awsAccountId": "123456789012",
"awsRegion": "us-east-2",
"connectionId": "20251217080657842fux3au9kh1p0j5s",
"version": 2
}
{
"code": "INVALID_REQUEST_BODY",
"message": "Request body validation failed.",
"fields": [
{
"name": "enabled",
"errors": "enabled is required"
}
]
}
{
"message": "Unauthorized"
}
{
"message": "Connection not found"
}
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
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
string
required
API key for authentication (starts with Get your API key from the API Access page in your Pictory dashboard.
pictai_)Authorization: YOUR_API_KEY
string
required
Must be set to
application/jsonBody Parameters
Do NOT include
awsRegion or awsAccountId in the request body. These fields are immutable and including them will cause errors.string
required
Updated name for the AWS connectionExample:
"UpdatedConnectionName"string
Updated description of the AWS connectionExample:
"Updated connection description"boolean
Whether the connection should be active (
true) or disabled (false). If not provided, the existing value is preserved.Example: trueinteger
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:
1Response
Returns the updated AWS connection object. Theversion 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": "INVALID_REQUEST_BODY",
"message": "Request body validation failed.",
"fields": [
{
"name": "enabled",
"errors": "enabled is required"
}
]
}
{
"message": "Unauthorized"
}
{
"message": "Connection not found"
}
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
// Replace 'YOUR_API_KEY' with your actual API key
// Replace 'YOUR_CONNECTION_ID' with your connection ID
const updateAwsConnection = async (apiKey, connectionId, updates) => {
const response = await fetch(`https://api.pictory.ai/pictoryapis/v1/awsconnections/${connectionId}`, {
method: 'PUT',
headers: {
'Authorization': `${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(updates)
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Failed: ${error.message}`);
}
return await response.json();
};
// Usage
try {
const connectionId = 'YOUR_CONNECTION_ID'; // ← Replace with your connection ID
const updates = {
name: 'UpdatedConnectionName',
description: 'Updated connection description',
enabled: true,
version: 1 // Get current version from Get Connection by ID endpoint
};
const result = await updateAwsConnection('YOUR_API_KEY', connectionId, updates); // ← Replace with your API key
console.log('Updated Connection:', result);
console.log('New Version:', result.version);
} catch (error) {
console.error('Error:', error.message);
}
# Replace 'YOUR_API_KEY' with your actual API key
# Replace 'YOUR_CONNECTION_ID' with your connection ID
import requests
def update_aws_connection(api_key, connection_id, updates):
"""Update an existing AWS S3 connection"""
url = f"https://api.pictory.ai/pictoryapis/v1/awsconnections/{connection_id}"
headers = {
"Authorization": api_key,
"Content-Type": "application/json"
}
response = requests.put(url, headers=headers, json=updates)
response.raise_for_status()
return response.json()
# Usage
try:
connection_id = "YOUR_CONNECTION_ID" # ← Replace with your connection ID
updates = {
"name": "UpdatedConnectionName",
"description": "Updated connection description",
"enabled": True,
"version": 1 # Get current version from Get Connection by ID endpoint
}
result = update_aws_connection("YOUR_API_KEY", connection_id, updates) # ← Replace with your API key
print(f"Updated Connection: {result}")
print(f"New Version: {result['version']}")
except requests.exceptions.HTTPError as e:
if e.response.status_code == 404:
print("Error: Connection not found")
else:
error = e.response.json()
print(f"Error: {error.get('message', 'Request failed')}")
<?php
// Replace 'YOUR_API_KEY' with your actual API key
// Replace 'YOUR_CONNECTION_ID' with your connection ID
function updateAwsConnection($apiKey, $connectionId, $updates) {
$url = 'https://api.pictory.ai/pictoryapis/v1/awsconnections/' . $connectionId;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $apiKey,
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($updates));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 404) {
throw new Exception('Connection not found');
}
if ($httpCode !== 200) {
$error = json_decode($response, true);
throw new Exception($error['message'] ?? 'Request failed');
}
return json_decode($response, true);
}
// Usage
try {
$connectionId = 'YOUR_CONNECTION_ID'; // ← Replace with your connection ID
$updates = [
'name' => 'UpdatedConnectionName',
'description' => 'Updated connection description',
'enabled' => true,
'version' => 1 // Get current version from Get Connection by ID endpoint
];
$result = updateAwsConnection('YOUR_API_KEY', $connectionId, $updates); // ← Replace with your API key
echo "Updated Connection:\n";
print_r($result);
echo "New Version: " . $result['version'] . "\n";
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>
// Replace "YOUR_API_KEY" with your actual API key
// Replace "YOUR_CONNECTION_ID" with your connection ID
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type UpdateAwsConnectionRequest struct {
Name string `json:"name"`
Description string `json:"description"`
Enabled bool `json:"enabled"`
Version int `json:"version"`
}
type AwsConnection struct {
ConnectionID string `json:"connectionId"`
Name string `json:"name"`
Description string `json:"description"`
Enabled bool `json:"enabled"`
AWSAccountID string `json:"awsAccountId"`
AWSRegion string `json:"awsRegion"`
Version int `json:"version"`
}
func updateAwsConnection(apiKey, connectionId string, updates UpdateAwsConnectionRequest) (*AwsConnection, error) {
url := fmt.Sprintf("https://api.pictory.ai/pictoryapis/v1/awsconnections/%s", connectionId)
jsonData, err := json.Marshal(updates)
if err != nil {
return nil, err
}
req, err := http.NewRequest("PUT", url, bytes.NewBuffer(jsonData))
if err != nil {
return nil, err
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, err
}
if resp.StatusCode == http.StatusNotFound {
return nil, fmt.Errorf("connection not found")
}
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
}
var result AwsConnection
if err := json.Unmarshal(body, &result); err != nil {
return nil, err
}
return &result, nil
}
// Usage
func main() {
connectionId := "YOUR_CONNECTION_ID" // ← Replace with your connection ID
updates := UpdateAwsConnectionRequest{
Name: "UpdatedConnectionName",
Description: "Updated connection description",
Enabled: true,
Version: 1, // Get current version from Get Connection by ID endpoint
}
result, err := updateAwsConnection("YOUR_API_KEY", connectionId, updates) // ← Replace with your API key
if err != nil {
panic(err)
}
fmt.Printf("Updated Connection: %+v\n", result)
fmt.Printf("New Version: %d\n", result.Version)
}
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
404 Not Found
404 Not Found
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
401 Unauthorized
401 Unauthorized
Cause: Invalid or missing API keySolution:
- Verify your API key is correct and starts with
pictai_ - Check the
Authorizationheader is properly formatted:YOUR_API_KEY - Ensure your API key hasn’t expired
- Get a new API key from the API Access page
400 Bad Request - Missing Required Fields
400 Bad Request - Missing Required Fields
Cause: Required fields are missing from the request bodySolution:
- Ensure both
nameandversionfields are included - Verify the request body is valid JSON
- The
enabledfield is optional - if omitted, the existing value is preserved
400 Bad Request - Invalid Field Values
400 Bad Request - Invalid Field Values
Cause: Field values do not meet validation requirementsSolution:
namemust be a non-empty string (required)versionmust be a positive integer (required)enabledmust be a boolean value (trueorfalse) if provided (optional)descriptionshould be a string if provided (optional)- Do NOT include
awsRegionorawsAccountIdin the request - these fields cannot be changed
409 Conflict - Version Mismatch
409 Conflict - Version Mismatch
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
versionnumber from that response - Retry your update request with the new version number
403 Forbidden
403 Forbidden
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
awsRegionin the request body will cause a400 Bad Requesterror - Including
awsAccountIdin the request body will cause a400 Bad Requesterror - The
connectionIdis in the URL path and cannot be changed
- Create a new connection with the correct values using Create AWS Connection
- Update your video creation workflows to use the new connection ID
- 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
Was this page helpful?
