Skip to main content
PUT
https://api.pictory.ai
/
pictoryapis
/
v1
/
vimeo-connections
/
{connectionid}
Update Vimeo Connection
curl --request PUT \
  --url https://api.pictory.ai/pictoryapis/v1/vimeo-connections/{connectionid} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": 123,
  "name": "<string>",
  "description": "<string>",
  "enabled": true,
  "clientIdentifier": "<string>",
  "clientSecret": "<string>",
  "accessToken": "<string>"
}
'
{
  "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
}

​
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.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

​
API Endpoint

PUT https://api.pictory.ai/pictoryapis/v1/vimeo-connections/{connectionid}

​
Request Parameters

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

​
Path Parameters

​
connectionid
string
required
The unique identifier of the Vimeo connection to updateExample: "20251222155613307xv0nodhitf9cd0f"

​
Body Parameters

​
version
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 doesn’t match.Example: 1
​
name
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 charactersExample: "Updated Vimeo Account"
​
description
string
Updated description explaining the connection’s purpose or usage.Maximum length: 250 charactersExample: "Updated description for marketing videos"
​
enabled
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
​
clientIdentifier
string
Updated Vimeo application Client ID from your Vimeo app settings. Changes which Vimeo application this connection uses for authentication.Maximum length: 500 charactersExample: "updated_client_id_123"
​
clientSecret
string
Updated Vimeo application client secret from your app settings. Use this to rotate credentials. Keep this value secure.Maximum length: 500 charactersExample: "updated_secret_xyz789"
​
accessToken
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 charactersExample: "updated_token_1234567890abcdef"

​
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’ll only see the clientIdentifier.

​
Response Examples

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

​
Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
# 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

​
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 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 won’t match and the update fails
Example workflow: 
# 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

Cause: The required version field is missing from the request bodySolution:
  • Always include the current version number in your update request
  • Get the current version using the Get Vimeo Connection by ID endpoint
  • The version field is required for optimistic locking to prevent concurrent update conflicts
Cause: A connection with the specified name already exists in your accountSolution:
  • Choose a unique name for your connection
  • Keep the current name if you’re only updating other fields
  • Use the Get Vimeo Connections endpoint to see existing connection names
Cause: The version number doesn’t match the current version (someone else updated the connection)Solution:
  • Get the latest connection details using the 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.
Cause: Invalid or missing API keySolution:
  • 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
Cause: The connection ID doesn’t exist or you don’t have access to itSolution:
  • 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 endpoint to list all your connections

​
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: 
{
  "description": "New description",
  "version": 1
}

​
Full Updates

Update multiple fields in a single request: Example - Update multiple fields: 
{
  "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
  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
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.