Skip to main content
GET
/
pictoryapis
/
v1
/
awsconnections
Get AWS Private Connections
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections \
  --header 'Authorization: <authorization>'
import requests

url = "https://api.pictory.ai/pictoryapis/v1/awsconnections"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pictory.ai/pictoryapis/v1/awsconnections', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.pictory.ai/pictoryapis/v1/awsconnections"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "<authorization>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.pictory.ai/pictoryapis/v1/awsconnections")
.header("Authorization", "<authorization>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.pictory.ai/pictoryapis/v1/awsconnections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body
{
  "Items": [
    {
      "connectionId": "20251217080657842fux3au9kh1p0j5s",
      "name": "TestAWSConnection",
      "description": "Test AWS Connection for Documentation",
      "awsAccountId": "123456789012",
      "awsRegion": "us-east-2",
      "type": "AWS",
      "enabled": true,
      "createdDate": "2025-12-17T08:06:56.862Z",
      "updatedDate": "2025-12-17T08:06:56.862Z",
      "version": 1
    }
  ]
}
{
  "Items": []
}
{
  "message": "Unauthorized"
}

Overview

This endpoint retrieves a list of all AWS S3 private connections you have configured for your Pictory account. Use this to view your existing connections, check their status, and get connection IDs for use in video creation requests.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

Use Cases

View All Connections

See all your configured AWS S3 connections in one place

Get Connection IDs

Retrieve connection IDs to use in video creation requests

Check Status

Verify which connections are currently enabled or disabled

Audit Configuration

Review your AWS account IDs and regions

API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/awsconnections

Request Parameters

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.

Response

Returns an array of AWS connection objects in the Items field. If no connections are configured, returns an empty array.

Response Examples

{
  "Items": [
    {
      "connectionId": "20251217080657842fux3au9kh1p0j5s",
      "name": "TestAWSConnection",
      "description": "Test AWS Connection for Documentation",
      "awsAccountId": "123456789012",
      "awsRegion": "us-east-2",
      "type": "AWS",
      "enabled": true,
      "createdDate": "2025-12-17T08:06:56.862Z",
      "updatedDate": "2025-12-17T08:06:56.862Z",
      "version": 1
    }
  ]
}
{
  "Items": []
}
{
  "message": "Unauthorized"
}

Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
# Retrieve all AWS connections
# Replace YOUR_API_KEY with your actual API key

curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool
// Replace 'YOUR_API_KEY' with your actual API key

const getAwsConnections = async (apiKey) => {
  const response = await fetch('https://api.pictory.ai/pictoryapis/v1/awsconnections', {
    method: 'GET',
    headers: {
      'Authorization': `${apiKey}`
    }
  });

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

  return await response.json();
};

// Usage
try {
  const result = await getAwsConnections('YOUR_API_KEY');  // ← Replace with your API key
  console.log('Your AWS Connections:', result.Items);

  // Get the first connection ID
  if (result.Items.length > 0) {
    console.log('First Connection ID:', result.Items[0].connectionId);
  }
} catch (error) {
  console.error('Error:', error.message);
}
# Replace 'YOUR_API_KEY' with your actual API key

import requests

def get_aws_connections(api_key):
    """Retrieve all AWS S3 connections"""
    url = "https://api.pictory.ai/pictoryapis/v1/awsconnections"

    headers = {
        "Authorization": api_key
    }

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

    return response.json()

# Usage
try:
    result = get_aws_connections("YOUR_API_KEY")  # ← Replace with your API key
    print(f"Your AWS Connections: {result['Items']}")

    # Get the first connection ID
    if len(result['Items']) > 0:
        print(f"First Connection ID: {result['Items'][0]['connectionId']}")
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    print(f"Error: {error.get('message', 'Request failed')}")
<?php
// Replace 'YOUR_API_KEY' with your actual API key

function getAwsConnections($apiKey) {
    $url = 'https://api.pictory.ai/pictoryapis/v1/awsconnections';

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

    return json_decode($response, true);
}

// Usage
try {
    $result = getAwsConnections('YOUR_API_KEY');  // ← Replace with your API key
    echo "Your AWS Connections:\n";
    print_r($result['Items']);

    // Get the first connection ID
    if (count($result['Items']) > 0) {
        echo "First Connection ID: " . $result['Items'][0]['connectionId'] . "\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
// Replace "YOUR_API_KEY" with your actual API key

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

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"`
}

type AwsConnectionsResponse struct {
    Items []AwsConnection `json:"Items"`
}

func getAwsConnections(apiKey string) (*AwsConnectionsResponse, error) {
    url := "https://api.pictory.ai/pictoryapis/v1/awsconnections"

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

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

    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.StatusOK {
        return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
    }

    var result AwsConnectionsResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

// Usage
func main() {
    result, err := getAwsConnections("YOUR_API_KEY")  // ← Replace with your API key
    if err != nil {
        panic(err)
    }

    fmt.Printf("Your AWS Connections: %+v\n", result.Items)

    // Get the first connection ID
    if len(result.Items) > 0 {
        fmt.Printf("First Connection ID: %s\n", result.Items[0].ConnectionID)
    }
}

Common Use Cases

Find Connection ID for Video Creation

When creating videos with private S3 assets, you need to provide the awsConnectionId. Use this endpoint to retrieve it:
// Get all connections and find the one you need
const result = await getAwsConnections(apiKey);
const myConnection = result.Items.find(conn => conn.name === 'PictoryPrivateVideosConnection');

if (myConnection) {
  console.log('Use this ID in video requests:', myConnection.connectionId);
}

Check if Connections are Enabled

result = get_aws_connections(api_key)

for connection in result['Items']:
    status = "Active" if connection['enabled'] else "Disabled"
    print(f"{connection['name']}: {status}")

List All Regions

const result = await getAwsConnections(apiKey);
const regions = result.Items.map(conn => conn.awsRegion);
console.log('Configured regions:', [...new Set(regions)]);

Next Steps

Create AWS Connection

Set up a new AWS S3 private connection

Use in Videos

Learn how to use connection IDs in video creation

Get API Key

Access your API key from your Pictory dashboard

Troubleshooting

Common issues and solutions