Vimeo

---
name: vimeo
description: |
  Vimeo API integration with managed OAuth. Video hosting and sharing platform.
  Use this skill when users want to upload, manage, or organize videos, create showcases/albums, manage folders, or interact with the Vimeo community.
  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
  Requires network access and valid Maton API key.
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    homepage: "https://maton.ai"
    requires:
      env:
        - MATON_API_KEY
---

# Vimeo

Access the Vimeo API with managed OAuth authentication. Upload and manage videos, create showcases and folders, manage likes and watch later, and interact with the Vimeo community.

## Quick Start

```bash
# Get current user info
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/vimeo/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/vimeo/{resource}
```

The gateway proxies requests to `api.vimeo.com` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Vimeo OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=vimeo&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'vimeo'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

**Response:**
```json
{
  "connection": {
    "connection_id": "a6ecb894-3148-4f4c-a54c-e9d917e3f2a9",
    "status": "ACTIVE",
    "creation_time": "2026-02-09T08:56:53.522100Z",
    "last_updated_time": "2026-02-09T08:58:39.407864Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "vimeo",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Specifying Connection

If you have multiple Vimeo connections, specify which one to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/vimeo/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'a6ecb894-3148-4f4c-a54c-e9d917e3f2a9')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

### User Operations

#### Get Current User

```bash
GET /vimeo/me
```

**Response:**
```json
{
  "uri": "/users/254399456",
  "name": "Chris",
  "link": "https://vimeo.com/user254399456",
  "account": "free",
  "created_time": "2026-02-09T07:00:20+00:00",
  "pictures": {...},
  "metadata": {
    "connections": {
      "videos": {"uri": "/users/254399456/videos", "total": 2},
      "albums": {"uri": "/users/254399456/albums", "total": 0},
      "folders": {"uri": "/users/254399456/folders", "total": 0},
      "likes": {"uri": "/users/254399456/likes", "total": 0},
      "followers": {"uri": "/users/254399456/followers", "total": 0},
      "following": {"uri": "/users/254399456/following", "total": 0}
    }
  }
}
```

#### Get User by ID

```bash
GET /vimeo/users/{user_id}
```

#### Get User Feed

```bash
GET /vimeo/me/feed
```

### Video Operations

#### List User Videos

```bash
GET /vimeo/me/videos
```

**Response:**
```json
{
  "total": 2,
  "page": 1,
  "per_page": 25,
  "paging": {
    "next": null,
    "previous": null,
    "first": "/me/videos?page=1",
    "last": "/me/videos?page=1"
  },
  "data": [
    {
      "uri": "/videos/1163160198",
      "name": "My Video",
      "description": "Video description",
      "link": "https://vimeo.com/1163160198",
      "duration": 20,
      "width": 1920,
      "height": 1080,
      "created_time": "2026-02-09T07:05:00+00:00"
    }
  ]
}
```

#### Get Video

```bash
GET /vimeo/videos/{video_id}
```

#### Search Videos

```bash
GET /vimeo/videos?query=nature&per_page=10
```

Query parameters:
- `query` - Search query
- `per_page` - Results per page (max 100)
- `page` - Page number
- `sort` - Sort order: `relevant`, `date`, `alphabetical`, `plays`, `likes`, `comments`, `duration`
- `direction` - Sort direction: `asc`, `desc`

#### Update Video

```bash
PATCH /vimeo/videos/{video_id}
Content-Type: application/json

{
  "name": "New Video Title",
  "description": "Updated description"
}
```

#### Delete Video

```bash
DELETE /vimeo/videos/{video_id}
```

Returns 204 No Content on success.

### Folder Operations (Projects)

#### List Folders

```bash
GET /vimeo/me/folders
```

**Response:**
```json
{
  "total": 1,
  "page": 1,
  "per_page": 25,
  "data": [
    {
      "uri": "/users/254399456/projects/28177219",
      "name": "My Folder",
      "created_time": "2026-02-09T08:59:20+00:00",
      "privacy": {"view": "nobody"},
      "manage_link": "https://vimeo.com/user/254399456/folder/28177219"
    }
  ]
}
```

#### Create Folder

```bash
POST /vimeo/me/folders
Content-Type: application/json

{
  "name": "New Folder"
}
```

#### Update Folder

```bash
PATCH /vimeo/me/projects/{project_id}
Content-Type: application/json

{
  "name": "Renamed Folder"
}
```

#### Delete Folder

```bash
DELETE /vimeo/me/projects/{project_id}
```

Returns 204 No Content on success.

#### Get Folder Videos

```bash
GET /vimeo/me/projects/{project_id}/videos
```

#### Add Video to Folder

```bash
PUT /vimeo/me/projects/{project_id}/videos/{video_id}
```

Returns 204 No Content on success.

#### Remove Video from Folder

```bash
DELETE /vimeo/me/projects/{project_id}/videos/{video_id}
```

### Album Operations (Showcases)

#### List Albums

```bash
GET /vimeo/me/albums
```

#### Create Album

```bash
POST /vimeo/me/albums
Content-Type: application/json

{
  "name": "My Showcase",
  "description": "A collection of videos"
}
```

**Response:**
```json
{
  "uri": "/users/254399456/albums/12099981",
  "name": "My Showcase",
  "description": "A collection of videos",
  "created_time": "2026-02-09T09:00:00+00:00"
}
```

#### Update Album

```bash
PATCH /vimeo/me/albums/{album_id}
Content-Type: application/json

{
  "name": "Updated Showcase Name"
}
```

#### Delete Album

```bash
DELETE /vimeo/me/albums/{album_id}
```

Returns 204 No Content on success.

#### Get Album Videos

```bash
GET /vimeo/me/albums/{album_id}/videos
```

#### Add Vide