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

> Update an existing Vimeo connection configuration

## Overview

Update an existing Vimeo connection configuration including name, description, enabled status, and authentication credentials. The version number must be provided to prevent concurrent modification conflicts. When updating the connection name, it must remain unique within your account.

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

***

## API Endpoint

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

***

## Request Parameters

### Headers

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

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

### Path Parameters

<ParamField path="connectionid" type="string" required>
  The unique identifier of the Vimeo connection to update

  **Example:** `"20251222155613307xv0nodhitf9cd0f"`
</ParamField>

### Body Parameters

<ParamField body="version" type="integer" required>
  Current version number of the connection. Must match the version in the database to prevent conflicts from concurrent updates. Update fails if the version does not match.

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

<ParamField body="name" type="string">
  Updated display name for the Vimeo connection. Must be unique within your account and can only contain letters, numbers, spaces, underscores, and hyphens.

  **Maximum length:** 100 characters

  **Example:** `"Updated Vimeo Account"`
</ParamField>

<ParamField body="description" type="string">
  Updated description explaining the connection's purpose or usage.

  **Maximum length:** 250 characters

  **Example:** `"Updated description for marketing videos"`
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the connection should be active. Set to `true` to enable, or `false` to disable. Disabling prevents usage but retains all configuration.

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

<ParamField body="clientIdentifier" type="string">
  Updated Vimeo application Client ID from your [Vimeo app settings](https://developer.vimeo.com/apps). Changes which Vimeo application this connection uses for authentication.

  **Maximum length:** 500 characters

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

<ParamField body="clientSecret" type="string">
  Updated Vimeo application client secret from your app settings. Use this to rotate credentials. Keep this value secure.

  **Maximum length:** 500 characters

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

<ParamField body="accessToken" type="string">
  Updated Vimeo access token for API authentication. Use this to refresh or change the token when it expires or when changing permissions scope.

  **Maximum length:** 500 characters

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

***

## Response

Returns the updated Vimeo connection object with all current configuration details. The `version` number is automatically incremented with each successful update for optimistic locking. The response includes `connectionId`, `name`, `description`, `clientIdentifier`, `type`, `enabled` status, and timestamps. For security, sensitive credentials (`clientSecret` and `accessToken`) are never returned in API responses - you will only see the `clientIdentifier`.

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "connectionId": "20251222155613307xv0nodhitf9cd0f",
    "name": "Updated Vimeo Connection Name",
    "description": "Updated description for testing PUT endpoint",
    "clientIdentifier": "updated_client_id_456",
    "type": "VIMEO",
    "enabled": false,
    "createdDate": "2025-12-22T15:56:12.309Z",
    "updatedDate": "2025-12-22T16:19:16.058Z",
    "version": 4
  }
  ```

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

  ```json 400 - Duplicate Name theme={null}
  {
    "code": "DUPLICATE_CONNECTION",
    "message": "Connection with same name or account/region already exist.",
    "fields": []
  }
  ```

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

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

  ```json 500 - Internal Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  # Update a Vimeo connection
  # Replace YOUR_API_KEY with your actual API key
  # Replace CONNECTION_ID with the actual connection ID

  # Partial update - update only description
  curl --request PUT \
    --url https://api.pictory.ai/pictoryapis/v1/vimeo-connections/CONNECTION_ID \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "description": "Updated description",
      "version": 1
    }'

  # Full update - update multiple fields
  curl --request PUT \
    --url https://api.pictory.ai/pictoryapis/v1/vimeo-connections/CONNECTION_ID \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Updated Connection Name",
      "description": "Updated description for marketing videos",
      "enabled": false,
      "clientIdentifier": "new_client_id_456",
      "clientSecret": "new_secret_xyz789",
      "accessToken": "new_token_1234567890",
      "version": 1
    }' | python -m json.tool
  ```

  ```javascript JavaScript / Node.js theme={null}
  // Replace 'YOUR_API_KEY' with your actual API key

  const updateVimeoConnection = async (apiKey, connectionId, updates) => {
    const response = await fetch(`https://api.pictory.ai/pictoryapis/v1/vimeo-connections/${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 - Partial update
  try {
    const connectionId = '20251222155613307xv0nodhitf9cd0f';

    // First, get current connection to retrieve version
    const getResponse = await fetch(`https://api.pictory.ai/pictoryapis/v1/vimeo-connections/${connectionId}`, {
      headers: { 'Authorization': 'YOUR_API_KEY' }
    });
    const currentConnection = await getResponse.json();

    // Partial update - only update description
    const partialUpdate = await updateVimeoConnection('YOUR_API_KEY', connectionId, {
      description: 'Updated description',
      version: currentConnection.version
    });
    console.log('Partial Update Result:', partialUpdate);

    // Full update - update multiple fields
    const fullUpdate = await updateVimeoConnection('YOUR_API_KEY', connectionId, {
      name: 'Updated Connection Name',
      description: 'Updated description for marketing videos',
      enabled: false,
      clientIdentifier: 'new_client_id_456',
      clientSecret: 'new_secret_xyz789',
      accessToken: 'new_token_1234567890',
      version: partialUpdate.version  // Use updated version
    });
    console.log('Full Update Result:', fullUpdate);
    console.log('New Version:', fullUpdate.version);
  } catch (error) {
    console.error('Error:', error.message);
  }
  ```

  ```python Python theme={null}
  # Replace 'YOUR_API_KEY' with your actual API key

  import requests

  def update_vimeo_connection(api_key, connection_id, updates):
      """Update a Vimeo connection"""
      url = f"https://api.pictory.ai/pictoryapis/v1/vimeo-connections/{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 = "20251222155613307xv0nodhitf9cd0f"

      # First, get current connection to retrieve version
      get_url = f"https://api.pictory.ai/pictoryapis/v1/vimeo-connections/{connection_id}"
      get_response = requests.get(get_url, headers={"Authorization": "YOUR_API_KEY"})
      current_connection = get_response.json()

      # Partial update - only update description
      partial_update = update_vimeo_connection("YOUR_API_KEY", connection_id, {
          "description": "Updated description",
          "version": current_connection["version"]
      })
      print(f"Partial Update Result: {partial_update}")

      # Full update - update multiple fields
      full_update = update_vimeo_connection("YOUR_API_KEY", connection_id, {
          "name": "Updated Connection Name",
          "description": "Updated description for marketing videos",
          "enabled": False,
          "clientIdentifier": "new_client_id_456",
          "clientSecret": "new_secret_xyz789",
          "accessToken": "new_token_1234567890",
          "version": partial_update["version"]  # Use updated version
      })
      print(f"Full Update Result: {full_update}")
      print(f"New Version: {full_update['version']}")
  except requests.exceptions.HTTPError as e:
      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

  function updateVimeoConnection($apiKey, $connectionId, $updates) {
      $url = "https://api.pictory.ai/pictoryapis/v1/vimeo-connections/{$connectionId}";

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

      return json_decode($response, true);
  }

  // Usage
  try {
      $connectionId = '20251222155613307xv0nodhitf9cd0f';

      // First, get current connection to retrieve version
      $getUrl = "https://api.pictory.ai/pictoryapis/v1/vimeo-connections/{$connectionId}";
      $ch = curl_init($getUrl);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
      $currentConnection = json_decode(curl_exec($ch), true);
      curl_close($ch);

      // Partial update - only update description
      $partialUpdate = updateVimeoConnection('YOUR_API_KEY', $connectionId, [
          'description' => 'Updated description',
          'version' => $currentConnection['version']
      ]);
      echo "Partial Update Result:\n";
      print_r($partialUpdate);

      // Full update - update multiple fields
      $fullUpdate = updateVimeoConnection('YOUR_API_KEY', $connectionId, [
          'name' => 'Updated Connection Name',
          'description' => 'Updated description for marketing videos',
          'enabled' => false,
          'clientIdentifier' => 'new_client_id_456',
          'clientSecret' => 'new_secret_xyz789',
          'accessToken' => 'new_token_1234567890',
          'version' => $partialUpdate['version']  // Use updated version
      ]);
      echo "Full Update Result:\n";
      print_r($fullUpdate);
      echo "New Version: " . $fullUpdate['version'] . "\n";
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```

  ```go Go theme={null}
  // Replace "YOUR_API_KEY" with your actual API key

  package main

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

  type VimeoConnectionUpdate struct {
      Name             string `json:"name,omitempty"`
      Description      string `json:"description,omitempty"`
      Enabled          *bool  `json:"enabled,omitempty"`
      ClientIdentifier string `json:"clientIdentifier,omitempty"`
      ClientSecret     string `json:"clientSecret,omitempty"`
      AccessToken      string `json:"accessToken,omitempty"`
      Version          int    `json:"version"`
  }

  type VimeoConnectionResponse struct {
      ConnectionID     string `json:"connectionId"`
      Name             string `json:"name"`
      Description      string `json:"description"`
      ClientIdentifier string `json:"clientIdentifier"`
      Type             string `json:"type"`
      Enabled          bool   `json:"enabled"`
      CreatedDate      string `json:"createdDate"`
      UpdatedDate      string `json:"updatedDate"`
      Version          int    `json:"version"`
  }

  func updateVimeoConnection(apiKey string, connectionId string, updates VimeoConnectionUpdate) (*VimeoConnectionResponse, error) {
      url := fmt.Sprintf("https://api.pictory.ai/pictoryapis/v1/vimeo-connections/%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.StatusOK {
          return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
      }

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

      return &result, nil
  }

  // Usage
  func main() {
      connectionId := "20251222155613307xv0nodhitf9cd0f"

      // First, get current connection to retrieve version
      // (Assuming a getCurrentConnection function exists)
      currentVersion := 1 // Replace with actual version from GET request

      // Partial update - only update description
      partialUpdate := VimeoConnectionUpdate{
          Description: "Updated description",
          Version:     currentVersion,
      }

      result, err := updateVimeoConnection("YOUR_API_KEY", connectionId, partialUpdate)
      if err != nil {
          panic(err)
      }

      fmt.Printf("Partial Update Result: %+v\n", result)
      fmt.Printf("New Version: %d\n", result.Version)

      // Full update - update multiple fields
      enabled := false
      fullUpdate := VimeoConnectionUpdate{
          Name:             "Updated Connection Name",
          Description:      "Updated description for marketing videos",
          Enabled:          &enabled,
          ClientIdentifier: "new_client_id_456",
          ClientSecret:     "new_secret_xyz789",
          AccessToken:      "new_token_1234567890",
          Version:          result.Version, // Use updated version
      }

      fullResult, err := updateVimeoConnection("YOUR_API_KEY", connectionId, fullUpdate)
      if err != nil {
          panic(err)
      }

      fmt.Printf("Full Update Result: %+v\n", fullResult)
      fmt.Printf("New Version: %d\n", fullResult.Version)
  }
  ```
</CodeGroup>

***

## Optimistic Locking

This endpoint uses optimistic locking to prevent conflicts from concurrent updates:

1. **Get Current Version:** Retrieve the connection using the [Get Vimeo Connection by ID](/api-reference/vimeo-integration/get-vimeo-connection-by-id) endpoint to get the current version number
2. **Include Version:** Include the current `version` number in your update request
3. **Version Check:** The API verifies the version matches before applying changes
4. **Version Increment:** On successful update, the version number is automatically incremented
5. **Conflict Handling:** If another update occurred between your GET and PUT requests, the version will not match and the update fails

**Example workflow:**

```http theme={null}
# Step 1: Get current connection
GET https://api.pictory.ai/pictoryapis/v1/vimeo-connections/abc123
# Response includes: "version": 5

# Step 2: Update with current version
PUT https://api.pictory.ai/pictoryapis/v1/vimeo-connections/abc123
{
  "name": "New Name",
  "version": 5
}
# Response includes: "version": 6 (incremented)
```

***

## Error Handling

<AccordionGroup>
  <Accordion title="400 Bad Request - Missing Version Field" icon="exclamation-triangle">
    **Cause:** The required `version` field is missing from the request body

    **Solution:**

    * Always include the current `version` number in your update request
    * Get the current version using the [Get Vimeo Connection by ID](/api-reference/vimeo-integration/get-vimeo-connection-by-id) endpoint
    * The `version` field is required for optimistic locking to prevent concurrent update conflicts
  </Accordion>

  <Accordion title="400 Bad Request - Duplicate Connection Name" icon="clone">
    **Cause:** A connection with the specified name already exists in your account

    **Solution:**

    * Choose a unique name for your connection
    * Keep the current name if you are only updating other fields
    * Use the [Get Vimeo Connections](/api-reference/vimeo-integration/get-vimeo-connections) endpoint to see existing connection names
  </Accordion>

  <Accordion title="400 Bad Request - Version Conflict" icon="code-merge">
    **Cause:** The version number does not match the current version (someone else updated the connection)

    **Solution:**

    * Get the latest connection details using the [Get Vimeo Connection by ID](/api-reference/vimeo-integration/get-vimeo-connection-by-id) endpoint
    * Use the current `version` number from that response
    * Review the changes made by the other update before proceeding
    * 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="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="404 Not Found" icon="circle-xmark">
    **Cause:** The connection ID does not exist or you do not have access to it

    **Solution:**

    * Verify the connection ID is correct and complete
    * Ensure the connection belongs to your account
    * Check if the connection has been deleted
    * Connection IDs are case-sensitive - confirm the exact casing
    * Use the [Get Vimeo Connections](/api-reference/vimeo-integration/get-vimeo-connections) endpoint to list all your connections
  </Accordion>
</AccordionGroup>

***

## Update Strategies

### Partial Updates

Only include the `version` field and the fields you want to update. All other fields remain unchanged.

**Example - Update only description:**

```json theme={null}
{
  "description": "New description",
  "version": 1
}
```

### Full Updates

Update multiple fields in a single request:

**Example - Update multiple fields:**

```json theme={null}
{
  "name": "New Connection Name",
  "description": "New description",
  "enabled": false,
  "clientIdentifier": "new_client_id",
  "clientSecret": "new_client_secret",
  "accessToken": "new_access_token",
  "version": 1
}
```

### Credential Rotation

When rotating Vimeo credentials (client secret or access token):

1. Obtain new credentials from the [Vimeo Developer Portal](https://developer.vimeo.com/apps)
2. Get the current version of the connection
3. Update with the new credentials and current version
4. Test the connection to ensure the new credentials work
5. Revoke the old credentials in Vimeo if needed

<Warning>
  **Disabling Connections:** Setting `enabled: false` prevents the connection from being used for Vimeo operations, but all configuration is retained. Re-enable it later by setting `enabled: true`.
</Warning>