API Documentation

Getting Started

Get up and running with the WorthClip API in three steps:

1. Create an account at worthclip.com
2. Go to Settings > API Keys > Generate
3. Use the key in the Authorization header

curl https://greedy-mallard-11.convex.site/api/v1/usage \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

Authentication

All API requests (except /health) require a Bearer token in the Authorization header:

curl https://greedy-mallard-11.convex.site/api/v1/usage \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

API keys use the wc_ prefix and are shown only once at creation. You can generate and manage keys from the Settings page.

Base URL

https://greedy-mallard-11.convex.site/api/v1

All endpoints described below are relative to this base URL.

Endpoint Reference

Health

No authentication required.

curl https://greedy-mallard-11.convex.site/api/v1/health

# Response: { "status": "ok" }

Scoring

Asynchronous video scoring. Submit a video, then poll for results.

# Submit a video for scoring
curl -X POST https://greedy-mallard-11.convex.site/api/v1/score \
  -H "Authorization: Bearer wc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "youtubeVideoId": "dQw4w9WgXcQ" }'

# Response (202): { "data": { "jobId": "..." } }
# Response (200): { "data": { ... } }  (if already scored)

# Poll for scoring result
curl https://greedy-mallard-11.convex.site/api/v1/score/JOB_ID \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

# Response: { "data": { "status": "pending|processing|completed|failed", ... } }

Rate limited at 20 requests per minute.

Videos

# Get video summary
curl https://greedy-mallard-11.convex.site/api/v1/videos/dQw4w9WgXcQ/summary \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

# Get full video detail with score
curl https://greedy-mallard-11.convex.site/api/v1/videos/dQw4w9WgXcQ \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

Feed

Query parameters:

• limit -- Number of results (default 20)
• cursor -- Numeric offset for pagination
• minScore -- Minimum score filter (1-10)
• verdict -- Filter by verdict (must_watch, worth_watching, conditional, skip)
• channelId -- Filter by channel

curl "https://greedy-mallard-11.convex.site/api/v1/feed?limit=10&minScore=7&verdict=must_watch" \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

Channels

# List tracked channels
curl https://greedy-mallard-11.convex.site/api/v1/channels \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

# Look up a channel by URL
curl -X POST https://greedy-mallard-11.convex.site/api/v1/channels/lookup \
  -H "Authorization: Bearer wc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://youtube.com/@fireship" }'

# Track a channel
curl -X POST https://greedy-mallard-11.convex.site/api/v1/channels/track \
  -H "Authorization: Bearer wc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "CHANNEL_ID" }'

Persona

# Get current persona
curl https://greedy-mallard-11.convex.site/api/v1/persona \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

# Update persona
curl -X PUT https://greedy-mallard-11.convex.site/api/v1/persona \
  -H "Authorization: Bearer wc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "Senior Developer", "building": "AI agents", "techStack": "TypeScript, Python" }'

# Update learning goals
curl -X PUT https://greedy-mallard-11.convex.site/api/v1/goals \
  -H "Authorization: Bearer wc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goals": ["Learn Rust", "Master system design", "Build distributed systems"] }'

Usage

curl https://greedy-mallard-11.convex.site/api/v1/usage \
  -H "Authorization: Bearer wc_YOUR_API_KEY"

Rate Limits

Rate limit information is included in response headers:

• X-RateLimit-Limit -- Maximum requests per window
• X-RateLimit-Remaining -- Requests remaining in current window
• Retry-After -- Seconds to wait (included with 429 responses)

When rate limited, you will receive a 429 response. Wait for the duration indicated by the Retry-After header before retrying.

Error Format

All errors return a consistent JSON format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Common error codes:

OpenClaw Integration

WorthClip is available as an OpenClaw skill, allowing AI agents to score and retrieve YouTube video recommendations on your behalf. See the OpenClaw documentation for integration details.