Skip to main content
POST
https://api.pictory.ai
/
pictoryapis
/
v1
/
vimeo-connections
Create Vimeo Connection
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/vimeo-connections \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "enabled": true,
  "clientIdentifier": "<string>",
  "clientSecret": "<string>",
  "accessToken": "<string>"
}
'
{
  "name": "Test Vimeo Connection",
  "description": "Testing Vimeo connection via API",
  "enabled": true,
  "clientIdentifier": "test_client_id_123",
  "connectionId": "20251222155613307xv0nodhitf9cd0f",
  "version": 1
}

​
Overview

Create a new Vimeo connection using your authentication credentials and configuration. Each connection name must be unique within your account. For security, sensitive credentials (client secret and access token) are securely stored and never returned in subsequent API responses.
You need a valid API key and Vimeo developer credentials to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

​
API Endpoint

POST https://api.pictory.ai/pictoryapis/v1/vimeo-connections

​
Request Parameters

​
Headers

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

​
Body Parameters

​
name
string
required
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: "My Vimeo Account"
​
description
string
Optional description explaining the connection’s purpose or usage.Maximum length: 250 charactersExample: "Primary Vimeo account for marketing videos"
​
enabled
boolean
default:"true"
required
Whether the connection should be active immediately after creation. Set to true to enable, or false to create in a disabled state.Example: true
​
clientIdentifier
string
required
Vimeo application Client ID from your Vimeo app settings. This identifies your application to Vimeo’s API.Maximum length: 500 charactersExample: "abc123def456ghi789jkl012"
​
clientSecret
string
required
Vimeo application client secret from your app settings. Keep this confidential and never expose it in client-side code.Maximum length: 500 charactersExample: "xyz789abc123def456ghi789"
​
accessToken
string
required
Vimeo access token that grants your application permission to access Vimeo resources. Obtain this through Vimeo’s OAuth flow or from your app settings.Maximum length: 500 charactersExample: "1234567890abcdef1234567890abcdef"

​
Response

Returns the created Vimeo connection object including the connectionId, name, description, enabled status, and version number. For security, sensitive credentials (clientSecret and accessToken) are never returned in API responses - you’ll only see the clientIdentifier.

​
Response Examples

{
  "name": "Test Vimeo Connection",
  "description": "Testing Vimeo connection via API",
  "enabled": true,
  "clientIdentifier": "test_client_id_123",
  "connectionId": "20251222155613307xv0nodhitf9cd0f",
  "version": 1
}

​
Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
# Create a new Vimeo connection
# Replace YOUR_API_KEY with your actual API key

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/vimeo-connections \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Vimeo Account",
    "description": "Primary Vimeo account for marketing videos",
    "enabled": true,
    "clientIdentifier": "abc123def456ghi789jkl012",
    "clientSecret": "xyz789abc123def456ghi789",
    "accessToken": "1234567890abcdef1234567890abcdef"
  }' | python -m json.tool

​
Error Handling

Cause: A connection with the same name already exists in your accountSolution:
Cause: Required fields are missing or field values don’t meet validation requirementsSolution:
  • Ensure all required fields are included: name, enabled, clientIdentifier, clientSecret, accessToken
  • Verify field values don’t exceed maximum lengths:
    • name: 100 characters max
    • description: 250 characters max
    • clientIdentifier, clientSecret, accessToken: 500 characters max
  • Check that name only contains letters, numbers, spaces, underscores, and hyphens
  • Verify the request body is valid JSON
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 Vimeo client identifier, client secret, or access token is invalidSolution:
  • Verify your credentials in the Vimeo Developer Portal
  • Ensure you’re using the correct Client ID, Client Secret, and Access Token
  • Check that your Vimeo app has the necessary permissions (video upload and management)
  • Generate a new access token if the current one has expired

​
Prerequisites: Getting Vimeo Credentials

Before creating a Vimeo connection, you need to obtain credentials from Vimeo:
1

Step 1: Create a Vimeo App

  1. Go to the Vimeo Developer Portal
  2. Sign in with your Vimeo account
  3. Click Create App or New App
  4. Fill in the required details (app name, description, etc.)
  5. Click Create App
2

Step 2: Get Your Credentials

  1. Once your app is created, you’ll see the app details page
  2. Note down the Client Identifier (Client ID)
  3. Note down the Client Secret (keep this secure!)
  4. Generate an Access Token with the required scopes:
    • video - Upload and manage videos
    • private - Access private videos
3

Step 3: Configure Permissions

Make sure your Vimeo app has the necessary permissions enabled:
  • Video upload
  • Video management
  • Account access
Keep Your Credentials Secure: Never expose your Client Secret or Access Token in client-side code or public repositories. These credentials provide full access to your Vimeo account.