REST API Reference

The Vimeo Connector provides a REST API for programmatic access to all sync operations. This reference documents all available endpoints.

Base URL

https://vimeo.trustedgpt.io/api/v1

For self-hosted deployments, replace with your server URL.

Authentication

Currently, the API is unauthenticated (open access). Authentication will be added in a future release.

Common Response Formats

Success Response

{
  "status": "success",
  "data": { ... }
}

Error Response

{
  "status": "error",
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not a valid Vimeo URL",
    "details": { ... }
  }
}

Endpoints

Health Check

Check if the API is reachable and healthy.

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-10-17T14:22:10Z"
}

HTTP Status Codes:

200 OK - Service is healthy
503 Service Unavailable - Service is down

Create Sync Job

Start a new sync job for a Vimeo URL.

Endpoint: POST /sync

Request Body:

{
  "url": "https://vimeo.com/showcase/11708791",
  "mode": "auto"
}

Parameters:

url (required) - Vimeo URL to sync
mode (optional) - Sync mode: auto, full, or incremental. Default: auto

Response:

{
  "job_id": "sync_a1b2c3d4",
  "status": "queued",
  "created_at": "2025-10-17T14:22:10Z"
}

HTTP Status Codes:

201 Created - Job created successfully
400 Bad Request - Invalid URL or parameters
429 Too Many Requests - Rate limit exceeded

Example:

curl -X POST https://vimeo.trustedgpt.io/api/v1/sync \
  -H "Content-Type: application/json" \
  -d '{"url": "https://vimeo.com/showcase/11708791", "mode": "auto"}'

Get Sync Job Status

Retrieve the current status and progress of a sync job.

Endpoint: GET /sync/{job_id}

Path Parameters:

job_id (required) - Job ID returned from POST /sync

Response:

{
  "job_id": "sync_a1b2c3d4",
  "url": "https://vimeo.com/showcase/11708791",
  "mode": "auto",
  "status": "running",
  "progress": {
    "processed": 45,
    "total": 100,
    "percentage": 45,
    "current_video": "Introduction to Product Features"
  },
  "results": {
    "added": 0,
    "updated": 0,
    "deleted": 0,
    "unchanged": 0
  },
  "created_at": "2025-10-17T14:22:10Z",
  "updated_at": "2025-10-17T14:25:30Z"
}

Status Values:

queued - Job is waiting to start
running - Job is currently processing
completed - Job finished successfully
failed - Job encountered an error
cancelled - Job was cancelled by user

HTTP Status Codes:

200 OK - Job found
404 Not Found - Job ID doesn't exist

Example:

curl https://vimeo.trustedgpt.io/api/v1/sync/sync_a1b2c3d4

Cancel Sync Job

Cancel a running sync job.

Endpoint: POST /sync/{job_id}/cancel

Path Parameters:

job_id (required) - Job ID to cancel

Response:

{
  "job_id": "sync_a1b2c3d4",
  "status": "cancelled",
  "cancelled_at": "2025-10-17T14:30:00Z"
}

HTTP Status Codes:

200 OK - Job cancelled successfully
404 Not Found - Job ID doesn't exist
409 Conflict - Job already completed/cancelled

Example:

curl -X POST https://vimeo.trustedgpt.io/api/v1/sync/sync_a1b2c3d4/cancel

List Recent Jobs

Get a list of recent sync jobs.

Endpoint: GET /sync

Query Parameters:

limit (optional) - Number of jobs to return. Default: 10, Max: 100
offset (optional) - Pagination offset. Default: 0
status (optional) - Filter by status: queued, running, completed, failed, cancelled

Response:

{
  "jobs": [
    {
      "job_id": "sync_a1b2c3d4",
      "url": "https://vimeo.com/showcase/11708791",
      "status": "completed",
      "created_at": "2025-10-17T14:22:10Z"
    },
    ...
  ],
  "total": 25,
  "limit": 10,
  "offset": 0
}

Example:

curl "https://vimeo.trustedgpt.io/api/v1/sync?limit=10&status=completed"

Get Video Metadata

Retrieve metadata for a specific video.

Endpoint: GET /videos/{video_id}

Path Parameters:

video_id (required) - Vimeo video ID

Response:

{
  "video_id": "987654321",
  "title": "Introduction to Product Features",
  "description": "A comprehensive walkthrough of our latest product features.",
  "duration": 1245,
  "upload_date": "2024-01-15T10:30:00Z",
  "url": "https://vimeo.com/987654321",
  "thumbnail_url": "https://i.vimeocdn.com/video/987654321_640.jpg",
  "tags": ["product", "tutorial", "features"],
  "has_transcript": true,
  "synced_at": "2025-10-17T14:22:10Z"
}

HTTP Status Codes:

200 OK - Video found
404 Not Found - Video not synced yet

Example:

curl https://vimeo.trustedgpt.io/api/v1/videos/987654321

Get Video Transcript

Retrieve the transcript for a specific video.

Endpoint: GET /transcripts/{video_id}

Path Parameters:

video_id (required) - Vimeo video ID

Response:

Welcome to this comprehensive product walkthrough.

Today we're going to explore the latest features we've released in Q3 2024.

First, let's take a look at the new dashboard interface.

...

Content-Type: text/plain

HTTP Status Codes:

200 OK - Transcript found
404 Not Found - Video has no transcript or not synced

Example:

curl https://vimeo.trustedgpt.io/api/v1/transcripts/987654321

Export Sync Results

Export all data from a sync job as a ZIP archive.

Endpoint: GET /sync/{job_id}/export

Path Parameters:

job_id (required) - Job ID to export

Response: ZIP file containing:

metadata/ - JSON files for each video
transcripts/ - Text files for each transcript
summary.json - Job summary with results

Content-Type: application/zip

HTTP Status Codes:

200 OK - Export successful
404 Not Found - Job ID doesn't exist
202 Accepted - Export is being prepared (large jobs)

Example:

curl https://vimeo.trustedgpt.io/api/v1/sync/sync_a1b2c3d4/export -o results.zip

Rate Limits

API requests are rate-limited to prevent abuse:

Limits:

Anonymous requests: 60 requests per minute
Authenticated requests: (Future) 300 requests per minute

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1634567890

429 Response:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 30 seconds.",
    "retry_after": 30
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_URL`	400	Vimeo URL format is invalid
`RESOURCE_NOT_FOUND`	404	Video/showcase doesn't exist on Vimeo
`AUTHENTICATION_ERROR`	401	Vimeo API token invalid
`RATE_LIMIT_EXCEEDED`	429	Too many API requests
`INTERNAL_ERROR`	500	Unexpected server error

Webhooks (Future)

Webhook support for real-time notifications is planned for a future release.

Events:

sync.started - Job started processing
sync.progress - Job progress update (every 10%)
sync.completed - Job completed successfully
sync.failed - Job failed with error

SDK Support

Official SDKs are planned for:

Python
JavaScript/TypeScript
Ruby
PHP

For Developers:

How It Works - Architecture details
GitHub Repository - Source code

For Users:

Getting Started - Dashboard guide
Troubleshooting - Common issues

Base URL​

Authentication​

Common Response Formats​

Success Response​

Error Response​

Endpoints​

Health Check​

Create Sync Job​

Get Sync Job Status​

Cancel Sync Job​

List Recent Jobs​

Get Video Metadata​

Get Video Transcript​

Export Sync Results​

Rate Limits​

Error Codes​

Webhooks (Future)​

SDK Support​

Related Documentation​

Base URL

Authentication

Common Response Formats

Success Response

Error Response

Endpoints

Health Check

Create Sync Job

Get Sync Job Status

Cancel Sync Job

List Recent Jobs

Get Video Metadata

Get Video Transcript

Export Sync Results

Rate Limits

Error Codes

Webhooks (Future)

SDK Support

Related Documentation