> ## 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.

# Update AWS Private Connection

> Modify an existing AWS S3 private connection configuration

## 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.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

<Warning>
  **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.
</Warning>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Rename Connection" icon="pen">
    Update the connection name for better organization
  </Card>

  <Card title="Update Description" icon="file-pen">
    Modify the description to reflect usage changes
  </Card>

  <Card title="Enable/Disable" icon="toggle-on">
    Temporarily disable a connection without deleting it
  </Card>

  <Card title="Manage Settings" icon="sliders">
    Update connection settings as your needs change
  </Card>
</CardGroup>

***

## API Endpoint

```http theme={null}
PUT https://api.pictory.ai/pictoryapis/v1/awsconnections/{connectionid}
```

***

## Request Parameters

### Path Parameters

<ParamField path="connectionid" type="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
  ```
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```

  Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`
</ParamField>

### Body Parameters

<Warning>
  **Do NOT include `awsRegion` or `awsAccountId` in the request body.** These fields are immutable and including them will cause errors.
</Warning>

<ParamField body="name" type="string" required>
  Updated name for the AWS connection

  **Example:** `"UpdatedConnectionName"`
</ParamField>

<ParamField body="description" type="string">
  Updated description of the AWS connection

  **Example:** `"Updated connection description"`
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the connection should be active (`true`) or disabled (`false`). If not provided, the existing value is preserved.

  **Example:** `true`
</ParamField>

<ParamField body="version" type="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](/api-reference/aws-integration/get-aws-connection-by-id) endpoint.

  **Example:** `1`
</ParamField>

***

## 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

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "enabled": true,
    "name": "UpdatedConnectionName",
    "description": "Updated connection description",
    "awsAccountId": "123456789012",
    "awsRegion": "us-east-2",
    "connectionId": "20251217080657842fux3au9kh1p0j5s",
    "version": 2
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "code": "INVALID_REQUEST_BODY",
    "message": "Request body validation failed.",
    "fields": [
      {
        "name": "enabled",
        "errors": "enabled is required"
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "message": "Connection not found"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  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
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  # 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
  ```

  ```javascript JavaScript / Node.js theme={null}
  // 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);
  }
  ```

  ```python Python theme={null}
  # 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 PHP theme={null}
  <?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";
  }
  ?>
  ```

  ```go Go theme={null}
  // 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)
  }
  ```
</CodeGroup>

***

## Common Use Cases

### Rename a Connection

```javascript theme={null}
// 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

```python theme={null}
# 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

```javascript theme={null}
// 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

```python theme={null}
# 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

<AccordionGroup>
  <Accordion title="404 Not Found" icon="circle-xmark">
    **Cause:** The connection ID does not exist or has been deleted

    **Solution:**

    * Verify the connection ID is correct
    * Use the [Get AWS Connections](/api-reference/aws-integration/get-aws-connections) endpoint to list all available connections
    * Check if the connection was deleted
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    **Cause:** Invalid or missing API key

    **Solution:**

    * 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](https://app.pictory.ai/api-access)
  </Accordion>

  <Accordion title="400 Bad Request - Missing Required Fields" icon="exclamation-triangle">
    **Cause:** Required fields are missing from the request body

    **Solution:**

    * 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
  </Accordion>

  <Accordion title="400 Bad Request - Invalid Field Values" icon="exclamation-triangle">
    **Cause:** Field values do not meet validation requirements

    **Solution:**

    * `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
  </Accordion>

  <Accordion title="409 Conflict - Version Mismatch" icon="code-merge">
    **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](/api-reference/aws-integration/get-aws-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.
  </Accordion>

  <Accordion title="403 Forbidden" icon="ban">
    **Cause:** You do not have permission to update this connection

    **Solution:**

    * 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
  </Accordion>
</AccordionGroup>

***

## Important Notes

<Warning>
  **Cannot Change AWS Credentials**

  You 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](/api-reference/aws-integration/aws-private-connection)
  2. Update your video creation workflows to use the new connection ID
  3. Delete the old connection using [Delete AWS Connection](/api-reference/aws-integration/delete-aws-connection)
</Warning>

<Note>
  **Version Tracking**

  Each successful update increments the `version` number of the connection. This helps track configuration changes over time.
</Note>

<Tip>
  **Disabling vs Deleting**

  Instead 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.
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List All Connections" icon="list" href="/api-reference/aws-integration/get-aws-connections">
    Retrieve all your AWS S3 private connections
  </Card>

  <Card title="Get Connection Details" icon="magnifying-glass" href="/api-reference/aws-integration/get-aws-connection-by-id">
    Get details of a specific connection before updating
  </Card>

  <Card title="Get API Key" icon="key" href="https://app.pictory.ai/api-access">
    Access your API key from your Pictory dashboard
  </Card>

  <Card title="Delete Connection" icon="trash" href="/api-reference/aws-integration/delete-aws-connection">
    Permanently delete an AWS connection
  </Card>
</CardGroup>