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

# Delete AWS Private Connection

> Permanently remove an AWS S3 private connection

## Overview

This endpoint allows you to permanently delete an AWS S3 private connection from your Pictory account. Once deleted, the connection cannot be recovered and any video creation workflows using this connection will fail.

<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>
  **This action is permanent and cannot be undone.** Before deleting a connection, ensure:

  * No active video projects are using this connection
  * You have documented the connection settings if you may need them again
  * Consider disabling the connection temporarily instead of deleting it
</Warning>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Remove Unused Connections" icon="broom">
    Clean up connections that are no longer needed
  </Card>

  <Card title="Security Cleanup" icon="shield-xmark">
    Remove connections for decommissioned AWS accounts
  </Card>

  <Card title="Connection Migration" icon="right-left">
    Delete old connections after migrating to new AWS infrastructure
  </Card>

  <Card title="Account Cleanup" icon="trash-can">
    Remove test or development connections
  </Card>
</CardGroup>

***

## API Endpoint

```http theme={null}
DELETE 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 delete. 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>

***

## Response

### Success Response

A successful deletion returns **204 No Content** with an empty response body. This is the standard HTTP status code for successful deletions.

**Status Code:** `204 No Content`

**Response Body:** None (empty)

### Response Examples

<ResponseExample>
  ```text 204 - No Content theme={null}
  (Empty response body)
  ```

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

<CodeGroup>
  ```bash cURL theme={null}
  # Delete an AWS connection
  # Replace YOUR_API_KEY with your actual API key
  # Replace YOUR_CONNECTION_ID with your connection ID

  curl --request DELETE \
    --url https://api.pictory.ai/pictoryapis/v1/awsconnections/YOUR_CONNECTION_ID \
    --header 'Authorization: YOUR_API_KEY' | 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 deleteAwsConnection = async (apiKey, connectionId) => {
    const response = await fetch(`https://api.pictory.ai/pictoryapis/v1/awsconnections/${connectionId}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `${apiKey}`
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Failed: ${error.message}`);
    }

    // 204 No Content - successful deletion returns no body
    return { success: true, status: response.status };
  };

  // Usage
  try {
    const connectionId = 'YOUR_CONNECTION_ID';  // ← Replace with your connection ID
    const result = await deleteAwsConnection('YOUR_API_KEY', connectionId);  // ← Replace with your API key
    console.log('Connection deleted successfully');
  } 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 delete_aws_connection(api_key, connection_id):
      """Delete an AWS S3 connection permanently"""
      url = f"https://api.pictory.ai/pictoryapis/v1/awsconnections/{connection_id}"

      headers = {
          "Authorization": api_key
      }

      response = requests.delete(url, headers=headers)
      response.raise_for_status()

      # 204 No Content - successful deletion returns no body
      return {"success": True, "status": response.status_code}

  # Usage
  try:
      connection_id = "YOUR_CONNECTION_ID"  # ← Replace with your connection ID
      result = delete_aws_connection("YOUR_API_KEY", connection_id)  # ← Replace with your API key
      print("Connection deleted successfully")
  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 deleteAwsConnection($apiKey, $connectionId) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/awsconnections/' . $connectionId;

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey
      ]);

      $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 !== 204) {
          $error = json_decode($response, true);
          throw new Exception($error['message'] ?? 'Request failed');
      }

      // 204 No Content - successful deletion returns no body
      return ['success' => true, 'status' => $httpCode];
  }

  // Usage
  try {
      $connectionId = 'YOUR_CONNECTION_ID';  // ← Replace with your connection ID
      $result = deleteAwsConnection('YOUR_API_KEY', $connectionId);  // ← Replace with your API key
      echo "Connection deleted successfully\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 (
      "fmt"
      "net/http"
  )

  func deleteAwsConnection(apiKey, connectionId string) error {
      url := fmt.Sprintf("https://api.pictory.ai/pictoryapis/v1/awsconnections/%s", connectionId)

      req, err := http.NewRequest("DELETE", url, nil)
      if err != nil {
          return err
      }

      req.Header.Set("Authorization", apiKey)

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return err
      }
      defer resp.Body.Close()

      if resp.StatusCode == http.StatusNotFound {
          return fmt.Errorf("connection not found")
      }

      if resp.StatusCode != http.StatusNoContent {
          return fmt.Errorf("request failed (status %d)", resp.StatusCode)
      }

      // 204 No Content - successful deletion
      return nil
  }

  // Usage
  func main() {
      connectionId := "YOUR_CONNECTION_ID"  // ← Replace with your connection ID
      err := deleteAwsConnection("YOUR_API_KEY", connectionId)  // ← Replace with your API key
      if err != nil {
          panic(err)
      }

      fmt.Println("Connection deleted successfully")
  }
  ```
</CodeGroup>

***

## Common Use Cases

### Safe Deletion with Confirmation

```javascript theme={null}
// Check connection exists before deleting
const safeDelete = async (apiKey, connectionId) => {
  try {
    // First, verify the connection exists
    const connection = await getAwsConnectionById(apiKey, connectionId);
    console.log(`About to delete: ${connection.name}`);

    // Confirm with user (in a real app)
    const confirmed = true; // Replace with actual user confirmation

    if (confirmed) {
      const result = await deleteAwsConnection(apiKey, connectionId);
      console.log('Connection deleted successfully');
    }
  } catch (error) {
    console.error('Delete failed:', error.message);
  }
};
```

### Delete After Migration

```python theme={null}
# Delete old connection after creating new one
def migrate_connection(api_key, old_connection_id, new_aws_account, new_region):
    # Create new connection
    new_connection = create_aws_connection(api_key, {
        "name": "MigratedConnection",
        "description": "Migrated to new AWS account",
        "awsAccountId": new_aws_account,
        "awsRegion": new_region,
        "enabled": True
    })

    print(f"New connection created: {new_connection['connectionId']}")

    # Delete old connection (returns 204 No Content on success)
    delete_aws_connection(api_key, old_connection_id)
    print("Old connection deleted successfully")

    return new_connection['connectionId']
```

### Bulk Cleanup

```javascript theme={null}
// Delete multiple unused connections
const cleanupConnections = async (apiKey, connectionIdsToDelete) => {
  const results = [];

  for (const connectionId of connectionIdsToDelete) {
    try {
      await deleteAwsConnection(apiKey, connectionId);
      results.push({ connectionId, status: 'deleted' });
    } catch (error) {
      results.push({ connectionId, status: 'failed', error: error.message });
    }
  }

  return results;
};

// Usage
const toDelete = ['connection-id-1', 'connection-id-2', 'connection-id-3'];
const results = await cleanupConnections(apiKey, toDelete);
console.log('Cleanup results:', results);
```

### Delete with Audit Trail

```python theme={null}
# Delete connection and log the action
import logging
from datetime import datetime

def delete_with_audit(api_key, connection_id, reason):
    # Get connection details before deletion
    connection = get_aws_connection_by_id(api_key, connection_id)

    # Log deletion
    logging.info(f"Deleting connection: {connection['name']}")
    logging.info(f"AWS Account: {connection['awsAccountId']}")
    logging.info(f"Region: {connection['awsRegion']}")
    logging.info(f"Reason: {reason}")
    logging.info(f"Timestamp: {datetime.now().isoformat()}")

    # Perform deletion (returns 204 No Content on success)
    delete_aws_connection(api_key, connection_id)

    logging.info("Deletion completed successfully")

    return True
```

***

## Error Handling

<AccordionGroup>
  <Accordion title="404 Not Found" icon="circle-xmark">
    **Cause:** The connection ID does not exist or has already 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 already 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="403 Forbidden" icon="ban">
    **Cause:** You do not have permission to delete 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>

  <Accordion title="409 Conflict - Connection In Use" icon="exclamation-triangle">
    **Cause:** The connection is currently being used by active video projects

    **Solution:**

    * Check for active videos using this connection
    * Wait for ongoing video rendering to complete
    * Update video projects to use a different connection
    * Disable the connection instead of deleting it
  </Accordion>
</AccordionGroup>

***

## Important Considerations

<Warning>
  **Before Deleting a Connection**

  1. **Check for active usage**: Ensure no videos are currently being processed with this connection
  2. **Document settings**: Save the AWS Account ID, Region, and IAM role configuration if you may need to recreate it
  3. **Update workflows**: Modify any automated workflows that reference this connection ID
  4. **Consider disabling**: Use the [Update endpoint](/api-reference/aws-integration/update-aws-connection) to disable instead of delete
</Warning>

<Note>
  **Alternative to Deletion**

  Instead of permanently deleting a connection, consider:

  * **Disabling it**: Set `enabled: false` using the [Update endpoint](/api-reference/aws-integration/update-aws-connection)
  * **Renaming it**: Add "DEPRECATED" to the name to mark it as inactive
  * This preserves the configuration for future reference while preventing its use
</Note>

<Tip>
  **When to Delete vs Disable**

  **Delete when:**

  * AWS account has been closed
  * Connection was created for testing only
  * Security requires removing all traces of the connection

  **Disable when:**

  * Temporarily pausing usage
  * May need to re-enable later
  * Want to preserve configuration for reference
</Tip>

***

## Deletion Impact

When you delete an AWS connection:

1. **Immediate Effects:**
   * Connection ID becomes invalid immediately
   * Cannot be used in new video creation requests
   * Connection appears in no API listings

2. **Video Projects:**
   * Existing videos remain accessible
   * New videos cannot be created using this connection
   * In-progress videos using this connection may fail

3. **Cannot Be Undone:**
   * Deleted connections cannot be recovered
   * Must create a new connection to restore access
   * New connection will have a different connection ID

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List All Connections" icon="list" href="/api-reference/aws-integration/get-aws-connections">
    View all connections before deleting
  </Card>

  <Card title="Get Connection Details" icon="magnifying-glass" href="/api-reference/aws-integration/get-aws-connection-by-id">
    Verify connection details before deletion
  </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="Create New Connection" icon="plus" href="/api-reference/aws-integration/aws-private-connection">
    Set up a replacement connection
  </Card>
</CardGroup>