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

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

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

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

List Connections

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

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

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:

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

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:

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

GET /vimeo/me

Response:

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

GET /vimeo/users/{user_id}

Get User Feed

GET /vimeo/me/feed

Video Operations

List User Videos

GET /vimeo/me/videos

Response:

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

GET /vimeo/videos/{video_id}

Search Videos

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

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

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

Delete Video

DELETE /vimeo/videos/{video_id}

Returns 204 No Content on success.

Folder Operations (Projects)

List Folders

GET /vimeo/me/folders

Response:

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

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

{
  "name": "New Folder"
}

Update Folder

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

{
  "name": "Renamed Folder"
}

Delete Folder

DELETE /vimeo/me/projects/{project_id}

Returns 204 No Content on success.

Get Folder Videos

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

Add Video to Folder

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

Returns 204 No Content on success.

Remove Video from Folder

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

Album Operations (Showcases)

List Albums

GET /vimeo/me/albums

Create Album

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

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

Response:

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

Update Album

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

{
  "name": "Updated Showcase Name"
}

Delete Album

DELETE /vimeo/me/albums/{album_id}

Returns 204 No Content on success.

Get Album Videos

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

Add Video to Album

PUT /vimeo/me/albums/{album_id}/videos/{video_id}

Returns 204 No Content on success.

Remove Video from Album

DELETE /vimeo/me/albums/{album_id}/videos/{video_id}

Comments

Get Video Comments

GET /vimeo/videos/{video_id}/comments

Add Comment

POST /vimeo/videos/{video_id}/comments
Content-Type: application/json

{
  "text": "Great video!"
}

Response:

{
  "uri": "/videos/1163160198/comments/21372988",
  "text": "Great video!",
  "created_on": "2026-02-09T09:05:00+00:00"
}

Delete Comment

DELETE /vimeo/videos/{video_id}/comments/{comment_id}

Returns 204 No Content on success.

Likes

Get Liked Videos

GET /vimeo/me/likes

Like a Video

PUT /vimeo/me/likes/{video_id}

Returns 204 No Content on success.

Unlike a Video

DELETE /vimeo/me/likes/{video_id}

Returns 204 No Content on success.

Watch Later

Get Watch Later List

GET /vimeo/me/watchlater

Add to Watch Later

PUT /vimeo/me/watchlater/{video_id}

Returns 204 No Content on success.

Remove from Watch Later

DELETE /vimeo/me/watchlater/{video_id}

Returns 204 No Content on success.

Followers and Following

Get Followers

GET /vimeo/me/followers

Get Following

GET /vimeo/me/following

Follow a User

PUT /vimeo/me/following/{user_id}

Unfollow a User

DELETE /vimeo/me/following/{user_id}

Channels and Categories

List All Channels

GET /vimeo/channels

Get Channel

GET /vimeo/channels/{channel_id}

List All Categories

GET /vimeo/categories

Response:

{
  "total": 10,
  "data": [
    {"uri": "/categories/animation", "name": "Animation"},
    {"uri": "/categories/comedy", "name": "Comedy"},
    {"uri": "/categories/documentary", "name": "Documentary"}
  ]
}

Get Category Videos

GET /vimeo/categories/{category}/videos

Pagination

Vimeo uses page-based pagination:

GET /vimeo/me/videos?page=1&per_page=25

Response:

{
  "total": 50,
  "page": 1,
  "per_page": 25,
  "paging": {
    "next": "/me/videos?page=2",
    "previous": null,
    "first": "/me/videos?page=1",
    "last": "/me/videos?page=2"
  },
  "data": [...]
}

Parameters:

• page - Page number (default 1)
• per_page - Results per page (default 25, max 100)

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/vimeo/me/videos',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/vimeo/me/videos',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

Python (Create Folder)

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/vimeo/me/folders',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={'name': 'New Folder'}
)
folder = response.json()
print(f"Created folder: {folder['uri']}")

Python (Update Video)

import os
import requests

video_id = "1163160198"
response = requests.patch(
    f'https://gateway.maton.ai/vimeo/videos/{video_id}',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Updated Title',
        'description': 'New description'
    }
)
video = response.json()
print(f"Updated video: {video['name']}")

Notes

• Video IDs are numeric (e.g., 1163160198)
• User IDs are numeric (e.g., 254399456)
• Folders are called "projects" in the API paths
• Albums are also known as "Showcases" in the Vimeo UI
• DELETE and PUT operations return 204 No Content on success
• Video uploads require the TUS protocol (not covered here)
• Rate limits vary by account type
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Vimeo errors include detailed messages:

{
  "error": "Your access token does not have the \"create\" scope"
}

Troubleshooting: Invalid API Key

When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

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

Resources

• Vimeo API Reference
• Vimeo Developer Portal
• Vimeo API Authentication
• Vimeo Upload API