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

# Create Vimeo Connection

> Connect your Vimeo account to enable automatic video uploads

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

<Note>
  You need a valid API key and Vimeo developer credentials 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}
POST https://api.pictory.ai/pictoryapis/v1/vimeo-connections
```

***

## Request Parameters

### Headers

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

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

### Body Parameters

<ParamField body="name" type="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 characters

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

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

  **Maximum length:** 250 characters

  **Example:** `"Primary Vimeo account for marketing videos"`
</ParamField>

<ParamField body="enabled" type="boolean" required default="true">
  Whether the connection should be active immediately after creation. Set to `true` to enable, or `false` to create in a disabled state.

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

<ParamField body="clientIdentifier" type="string" required>
  Vimeo application Client ID from your [Vimeo app settings](https://developer.vimeo.com/apps). This identifies your application to Vimeo's API.

  **Maximum length:** 500 characters

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

<ParamField body="clientSecret" type="string" required>
  Vimeo application client secret from your app settings. Keep this confidential and never expose it in client-side code.

  **Maximum length:** 500 characters

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

<ParamField body="accessToken" type="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 characters

  **Example:** `"1234567890abcdef1234567890abcdef"`
</ParamField>

***

## 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 will only see the `clientIdentifier`.

### Response Examples

<ResponseExample>
  ```json 201 - Success theme={null}
  {
    "name": "Test Vimeo Connection",
    "description": "Testing Vimeo connection via API",
    "enabled": true,
    "clientIdentifier": "test_client_id_123",
    "connectionId": "20251222155613307xv0nodhitf9cd0f",
    "version": 1
  }
  ```

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

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

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

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

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

  const createVimeoConnection = async (apiKey, connectionData) => {
    const response = await fetch('https://api.pictory.ai/pictoryapis/v1/vimeo-connections', {
      method: 'POST',
      headers: {
        'Authorization': `${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(connectionData)
    });

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

    return await response.json();
  };

  // Usage
  try {
    const connectionData = {
      name: 'My Vimeo Account',
      description: 'Primary Vimeo account for marketing videos',
      enabled: true,
      clientIdentifier: 'abc123def456ghi789jkl012',
      clientSecret: 'xyz789abc123def456ghi789',
      accessToken: '1234567890abcdef1234567890abcdef'
    };

    const result = await createVimeoConnection('YOUR_API_KEY', connectionData);
    console.log('Connection Created:', result);
    console.log('Connection ID:', result.connectionId);
  } catch (error) {
    console.error('Error:', error.message);
  }
  ```

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

  import requests

  def create_vimeo_connection(api_key, connection_data):
      """Create a new Vimeo connection"""
      url = "https://api.pictory.ai/pictoryapis/v1/vimeo-connections"

      headers = {
          "Authorization": api_key,
          "Content-Type": "application/json"
      }

      response = requests.post(url, headers=headers, json=connection_data)
      response.raise_for_status()

      return response.json()

  # Usage
  try:
      connection_data = {
          "name": "My Vimeo Account",
          "description": "Primary Vimeo account for marketing videos",
          "enabled": True,
          "clientIdentifier": "abc123def456ghi789jkl012",
          "clientSecret": "xyz789abc123def456ghi789",
          "accessToken": "1234567890abcdef1234567890abcdef"
      }

      result = create_vimeo_connection("YOUR_API_KEY", connection_data)
      print(f"Connection Created: {result}")
      print(f"Connection ID: {result['connectionId']}")
  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 createVimeoConnection($apiKey, $connectionData) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/vimeo-connections';

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey,
          'Content-Type: application/json'
      ]);
      curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($connectionData));

      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);

      if ($httpCode !== 201) {
          $error = json_decode($response, true);
          throw new Exception($error['message'] ?? 'Request failed');
      }

      return json_decode($response, true);
  }

  // Usage
  try {
      $connectionData = [
          'name' => 'My Vimeo Account',
          'description' => 'Primary Vimeo account for marketing videos',
          'enabled' => true,
          'clientIdentifier' => 'abc123def456ghi789jkl012',
          'clientSecret' => 'xyz789abc123def456ghi789',
          'accessToken' => '1234567890abcdef1234567890abcdef'
      ];

      $result = createVimeoConnection('YOUR_API_KEY', $connectionData);
      echo "Connection Created:\n";
      print_r($result);
      echo "Connection ID: " . $result['connectionId'] . "\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 VimeoConnectionRequest struct {
      Name             string `json:"name"`
      Description      string `json:"description"`
      Enabled          bool   `json:"enabled"`
      ClientIdentifier string `json:"clientIdentifier"`
      ClientSecret     string `json:"clientSecret"`
      AccessToken      string `json:"accessToken"`
  }

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

  func createVimeoConnection(apiKey string, connectionData VimeoConnectionRequest) (*VimeoConnectionResponse, error) {
      url := "https://api.pictory.ai/pictoryapis/v1/vimeo-connections"

      jsonData, err := json.Marshal(connectionData)
      if err != nil {
          return nil, err
      }

      req, err := http.NewRequest("POST", 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.StatusCreated {
          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() {
      connectionData := VimeoConnectionRequest{
          Name:             "My Vimeo Account",
          Description:      "Primary Vimeo account for marketing videos",
          Enabled:          true,
          ClientIdentifier: "abc123def456ghi789jkl012",
          ClientSecret:     "xyz789abc123def456ghi789",
          AccessToken:      "1234567890abcdef1234567890abcdef",
      }

      result, err := createVimeoConnection("YOUR_API_KEY", connectionData)
      if err != nil {
          panic(err)
      }

      fmt.Printf("Connection Created: %+v\n", result)
      fmt.Printf("Connection ID: %s\n", result.ConnectionID)
  }
  ```
</CodeGroup>

***

## Error Handling

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

    **Solution:**

    * Choose a unique name for your connection
    * Use the [Get Vimeo Connections](/api-reference/vimeo-integration/get-vimeo-connections) endpoint to see existing connection names
    * Or update the existing connection using the [Update Vimeo Connection](/api-reference/vimeo-integration/update-vimeo-connection) endpoint
  </Accordion>

  <Accordion title="400 Bad Request - Validation Error" icon="exclamation-triangle">
    **Cause:** Required fields are missing or field values do not meet validation requirements

    **Solution:**

    * Ensure all required fields are included: `name`, `enabled`, `clientIdentifier`, `clientSecret`, `accessToken`
    * Verify field values do not 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
  </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="Invalid Vimeo Credentials" icon="key">
    **Cause:** The Vimeo client identifier, client secret, or access token is invalid

    **Solution:**

    * Verify your credentials in the [Vimeo Developer Portal](https://developer.vimeo.com/apps)
    * Ensure you are 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
  </Accordion>
</AccordionGroup>

***

## Prerequisites: Getting Vimeo Credentials

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

<Steps>
  <Step title="Step 1: Create a Vimeo App">
    1. Go to the [Vimeo Developer Portal](https://developer.vimeo.com/apps)
    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**
  </Step>

  <Step title="Step 2: Get Your Credentials">
    1. Once your app is created, you will 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
  </Step>

  <Step title="Step 3: Configure Permissions">
    Make sure your Vimeo app has the necessary permissions enabled:

    * Video upload
    * Video management
    * Account access
  </Step>
</Steps>

<Warning>
  **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.
</Warning>