# Algrow API Documentation

> Base URL: https://api.algrow.online
> All plans: Channel search, scraping, and data endpoints
> Professional or Ultimate: Text-to-speech and voice generation endpoints

## Authentication

All endpoints require a valid API key via one of:
- Header: `Authorization: Bearer algrow_...`
- Query parameter: `?api_key=algrow_...`
- Form field: `api_key=algrow_...`

---

## GET /api/health

Health check endpoint. No authentication required.

**Response:**
```json
{"status": "healthy", "timestamp": "2026-03-24T12:00:00Z"}
```

---

## GET /api/voices

List available TTS voices. Supports filtering by gender, language, accent, age, and use case.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| search | string | — | Search voices by name, labels, or description |
| gender | string | — | Filter: male, female |
| language | string | — | Filter by language (e.g. English, Spanish) |
| accent | string | — | Filter by accent (e.g. British, American) |
| age | string | — | Filter: young, middle_aged, old |
| use_case | string | — | Filter: narration, conversational, characters, news |
| sort | string | trending | Sort: trending, name, newest |
| page | integer | 1 | Page number |
| per_page | integer | 50 | Results per page (max 100) |

**Response:**
```json
{
  "voices": [
    {
      "voice_id": "pNInz6obpgDQGcFmaJgB",
      "name": "Adam",
      "gender": "male",
      "accent": "American",
      "age": "middle_aged",
      "language": "English",
      "use_case": "narration",
      "description": "Deep, authoritative voice",
      "preview_url": "https://audio.algrow.online/previews/adam.mp3",
      "provider": "elevenlabs"
    }
  ],
  "total": 1000,
  "page": 1,
  "per_page": 50
}
```

---

## POST /api/generate-simple

Generate text-to-speech audio. Async — returns a job_id immediately.

**Content-Type:** multipart/form-data

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| text | string | Yes | — | Text to convert (max 5000 chars) |
| voice_id | string | Yes | — | Voice ID from /api/voices |
| model_id | string | No | eleven_multilingual_v2 | TTS model |
| stability | float | No | 0.5 | Voice stability (0-1) |
| similarity_boost | float | No | 0.75 | Voice similarity (0-1) |
| style | float | No | 0.0 | Style exaggeration (0-1) |
| speaking_rate | float | No | 1.0 | Speed (0.5-2.0) |

**Response:**
```json
{
  "success": true,
  "job_id": "300040",
  "message": "Generation started",
  "voice_name": "Adam"
}
```

---

## GET /api/job-status/:job_id

Poll for TTS/media generation job status.

**Response (completed):**
```json
{
  "job_id": "300040",
  "status": "completed",
  "audio_url": "https://audio.algrow.online/voiceovers/abc123.mp3",
  "duration_seconds": 12.5,
  "character_count": 150
}
```

**Statuses:** pending, processing, completed, failed

---

## GET /api/jobs

List your generation jobs with pagination.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| page | integer | 1 | Page number |
| per_page | integer | 20 | Results per page |
| status | string | — | Filter: pending, processing, completed, failed |

---

## GET /api/voices/stealth

List your custom cloned voices.

**Response:**
```json
{
  "success": true,
  "voices": [
    {
      "voice_id": "custom_abc123",
      "name": "My Custom Voice",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}
```

---

## POST /api/voices/clone

Clone a voice from an audio sample. Costs 1 credit.

**Content-Type:** multipart/form-data

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | Yes | Name for the cloned voice |
| files | file | Yes | Audio file (MP3, WAV, M4A — max 10MB) |
| description | string | No | Voice description |
| removeBackgroundNoise | boolean | No | Clean up background noise |

---

## DELETE /api/voices/stealth/:voice_id

Delete a custom cloned voice.

**Response:**
```json
{"success": true, "message": "Voice deleted"}
```

---

## POST /api/caption-remover

Remove captions/subtitles from a video. Costs 1 credit. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| video_url | string | Yes | URL of the video to process |

**Response:**
```json
{
  "success": true,
  "job_id": "a5358a1c-...",
  "message": "Caption removal queued. Poll /api/job-status/{job_id} for progress."
}
```

---

## POST /api/sora-watermark-remover

Remove Sora watermarks from AI-generated videos. Costs 2 credits. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| video_url | string | Yes | Sora video URL or direct video URL |

**Response:**
```json
{
  "success": true,
  "job_id": "b7429c3e-...",
  "message": "Sora watermark removal queued. Poll /api/job-status/{job_id} for progress."
}
```

---

## POST /api/generate-image

Generate an AI image. Costs 1 credit. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| prompt | string | Yes | — | Image description |
| model | string | No | nano-banana-2 | Model: nano-banana-2, flux-1.1-pro, gpt-image-1 |
| aspect_ratio | string | No | 16:9 | Aspect ratio (e.g. 1:1, 16:9, 9:16) |

---

## POST /api/generate-video

Generate an AI video. Credits vary by model. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| prompt | string | Yes | — | Video description |
| model | string | No | sora-2 | Model: sora-2, kling-2.6, veo-3 |
| seconds | string | No | 5 | Duration in seconds |
| size | string | No | 1280x720 | Resolution (e.g. 720x1280, 1920x1080) |
| input_reference_url | string | No | — | Reference image URL (for image-to-video) |
| duration | string | No | — | Alternative to seconds for some models |

---

## POST /api/youtube-scraper

Scrape video data from a YouTube channel or single video. Async job — submit, then poll for results.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| url | string | Yes | — | YouTube channel URL or video URL |
| video_type | string | No | both | Type: shorts, videos, or both |
| sort | string | No | recent | Sort: recent or popular |
| max_videos | integer | No | 20 | Max videos to scrape (1-100) |
| include_transcripts | boolean | No | false | Include full video transcripts |
| include_comments | boolean | No | false | Include top comments per video |

**Response:**
```json
{
  "success": true,
  "job_id": 4521,
  "mode": "channel",
  "message": "Scraping job queued. Poll /api/youtube-scraper/{job_id} for results."
}
```

---

## GET /api/youtube-scraper/:job_id

Poll for YouTube scraping job results.

**Response (completed):**
```json
{
  "success": true,
  "job_id": 4521,
  "status": "completed",
  "result": {
    "total_videos": 10,
    "total_views": 1250000000,
    "total_likes": 42000000,
    "videos": [
      {
        "video_id": "dQw4w9WgXcQ",
        "title": "Video Title",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "view_count": 250000000,
        "like_count": 8500000,
        "comment_count": 2100000,
        "duration_seconds": 212,
        "duration_human": "3m 32s",
        "publish_date": "2025-10-15T14:00:00Z",
        "channel": "Channel Name",
        "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "transcript": "Full transcript text...",
        "comments": [
          {
            "author": "@user123",
            "text": "Great video!",
            "likes": 5200,
            "published_time": "2 months ago"
          }
        ]
      }
    ]
  }
}
```

---

## GET /api/terminated-channels/search

Search terminated/deleted YouTube channels. Returns channel metadata, growth metrics at time of termination, and top 3 videos per channel.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | — | Search query. Matches against channel titles and video titles. Comma-separated for multiple keywords. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort | string | date_desc | Sort: {field}_{asc|desc}. Fields: subs, views, videos, age, views_24h, subs_24h, views_48h, date, similarity |
| page | integer | 1 | Page number |
| per_page | integer | 20 | Results per page (max 50) |
| min_subs | integer | — | Minimum subscriber count |
| max_subs | integer | — | Maximum subscriber count |
| min_views | integer | — | Minimum total view count |
| max_views | integer | — | Maximum total view count |
| min_avg_views | integer | — | Minimum average views per video |
| max_avg_views | integer | — | Maximum average views per video |
| min_age | integer | — | Minimum channel age in days |
| max_age | integer | — | Maximum channel age in days |
| min_uploads | integer | — | Minimum number of videos |
| max_uploads | integer | — | Maximum number of videos |
| monetized | string | — | Filter: yes or no |
| min_views_24h | integer | — | Min views in last 24h before termination |
| max_views_24h | integer | — | Max views in last 24h before termination |
| min_views_48h | integer | — | Min views in last 48h before termination |
| max_views_48h | integer | — | Max views in last 48h before termination |

**Response:**
```json
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Channel Name",
      "subscriber_count": 340000,
      "view_count": 95000000,
      "avg_views_per_video": 2100000,
      "total_videos": 45,
      "primary_language": "English",
      "monetized": true,
      "is_low_quality": false,
      "thumbnail_url": "https://...",
      "first_upload_date": "2025-06-12",
      "terminated_date": "2026-03-10",
      "terminated_days_ago": 15,
      "view_increase_24h": 120000,
      "sub_increase_24h": 800,
      "view_increase_48h": 210000,
      "sub_increase_48h": 1400,
      "similarity_score": 85,
      "recent_videos": [
        {
          "video_id": "abc123",
          "title": "Top Video Title",
          "view_count": 12000000,
          "thumbnail_url": "https://...",
          "url": "https://www.youtube.com/watch?v=abc123"
        }
      ]
    }
  ]
}
```

---

## GET /api/channels/search

Search Shorts channels with semantic AI search, keyword matching, and advanced filters. Returns channel metadata, growth metrics, and recent videos.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | **required** | Search query. Pass a channel name, @handle, or YouTube channel URL to find similar competitors. Comma-separated for multiple, prefix with - to exclude. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort | string | subs_desc | Sort: {field}_{asc\|desc}. Fields: subs, views, videos, age, added, views_24h, subs_24h, views_48h, similarity |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 20 | Results per page (max 50) |
| min_subs / max_subs | integer | — | Subscriber count range |
| min_avg_views / max_avg_views | integer | — | Average views per video range |
| min_age / max_age | integer | — | Channel age in days range |
| min_uploads / max_uploads | integer | — | Number of videos range |
| min_views / max_views | integer | — | Total view count range |
| min_views_24h / max_views_24h | integer | — | Views gained in last 24 hours range |
| min_views_48h / max_views_48h | integer | — | Views gained in last 48 hours range |
| min_days_added / max_days_added | integer | — | Days since channel was added to Algrow |

**Response:**
```json
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Channel Name",
      "subscriber_count": 150000,
      "avg_views_per_video": 500000,
      "total_videos": 120,
      "channel_age_days": 365,
      "view_count": 60000000,
      "primary_language": "English",
      "thumbnail_url": "https://...",
      "view_increase_24h": 50000,
      "sub_increase_24h": 200,
      "view_increase_48h": 95000,
      "similarity_score": 82,
      "recent_videos": [
        {
          "video_id": "abc123",
          "title": "Video Title",
          "view_count": 2000000,
          "upload_date": "2026-03-20",
          "thumbnail_url": "https://...",
          "url": "https://www.youtube.com/shorts/abc123"
        }
      ]
    }
  ]
}
```

---

## GET /api/longform-channels/search

Search Longform channels with semantic AI search, keyword matching, and advanced filters. Returns channel metadata, growth metrics, monetization status, and recent videos with duration.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | **required** | Search query. Pass a channel name, @handle, or YouTube channel URL to find similar competitors. Comma-separated for multiple, prefix with - to exclude. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort | string | subs_desc | Sort: {field}_{asc\|desc}. Fields: subs, views, videos, age, total_views, added, views_24h, subs_24h, views_48h, similarity |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 20 | Results per page (max 50) |
| min_subs / max_subs | integer | — | Subscriber count range |
| min_avg_views / max_avg_views | integer | — | Average views per video range |
| min_age / max_age | integer | — | Channel age in days range |
| min_uploads / max_uploads | integer | — | Number of videos range |
| min_duration / max_duration | integer | — | Average video duration in seconds range |
| monetized | string | — | Filter by monetization: "yes" or "no" |
| min_views_24h / max_views_24h | integer | — | Views gained in last 24 hours range |
| min_views_48h / max_views_48h | integer | — | Views gained in last 48 hours range |
| min_days_added / max_days_added | integer | — | Days since channel was added to Algrow |

**Response:**
```json
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "name": "Channel Name",
      "subscriber_count": 500000,
      "avg_views_per_video": 200000,
      "total_videos": 80,
      "upload_day": 730,
      "view_count": 16000000,
      "primary_language": "English",
      "profile_picture": "https://...",
      "monetized": true,
      "url": "https://www.youtube.com/@ChannelName",
      "views_24h": 30000,
      "subs_24h": 150,
      "views_48h": 55000,
      "similarity_score": 76,
      "recent_videos": [
        {
          "video_id": "xyz789",
          "title": "Video Title",
          "view_count": 500000,
          "upload_date": "2026-03-18",
          "thumbnail_url": "https://...",
          "url": "https://www.youtube.com/watch?v=xyz789",
          "duration": 612
        }
      ]
    }
  ]
}
```

---

## GET /api/viral-videos/search

Search for viral videos across Shorts and Longform channels, or find videos similar to a specific video. Filter by video views, channel size, growth metrics, upload recency, and language.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | — | Search query. Uses similarity matching. Either `q` or `video_id` is required. |
| video_id | string | — | YouTube video ID (e.g. "dQw4w9WgXcQ"). Finds similar videos by title. Either `q` or `video_id` is required. |
| content_type | string | shorts | Content type: "shorts" or "longform" |
| channel_ids | string | — | Comma-separated channel IDs to filter by. Only returns videos from these channels. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort_by | string | views | Sort: "views", "recent", "upload_date", "similarity" |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 20 | Results per page (max 50) |
| min_video_views / max_video_views | integer | — | Video view count range |
| min_subs / max_subs | integer | — | Channel subscriber count range |
| min_uploads / max_uploads | integer | — | Channel video count range |
| min_channel_age / max_channel_age | integer | — | Channel age in days range |
| min_upload_date / max_upload_date | integer | — | Upload date range (days ago, 0 = today) |
| min_duration / max_duration | integer | — | Video duration in minutes range (longform only) |
| min_views_24h / max_views_24h | integer | — | Channel views gained in last 24h (shorts only) |
| min_views_48h / max_views_48h | integer | — | Channel views gained in last 48h (shorts only) |

**Response:**
```json
{
  "success": true,
  "content_type": "shorts",
  "page": 1,
  "per_page": 20,
  "count": 20,
  "videos": [
    {
      "video_id": "abc123",
      "title": "Video Title",
      "channel_name": "Channel Name",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 5000000,
      "thumbnail_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
      "upload_date": "2026-03-25",
      "url": "https://www.youtube.com/shorts/abc123",
      "subscriber_count": 200000,
      "duration": null,
      "view_increase_24h": 150000,
      "view_increase_48h": 280000,
      "similarity_score": 89
    }
  ]
}
```

---

## POST /api/thumbnail-search

Search for longform videos by thumbnail similarity. Provide a YouTube video URL, an image URL, or a text description to find videos with visually similar thumbnails using similarity matching.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| image_url | string | One of these three | — | URL of a thumbnail image to search with |
| video_url | string | One of these three | — | YouTube video URL — automatically extracts its thumbnail |
| q | string | One of these three | — | Text description of thumbnail style (e.g. "before and after transformation") |
| limit | integer | No | 20 | Max results to return (1-50) |
| min_similarity | float | No | 0.3 | Minimum similarity threshold (0-1) |
| min_views | integer | No | — | Minimum video view count filter |
| max_views | integer | No | — | Maximum video view count filter |
| min_upload_date | integer | No | — | Newest allowed upload (days ago, 0 = today) |
| max_upload_date | integer | No | — | Oldest allowed upload (days ago, e.g. 365 = 1 year) |

**Response:**
```json
{
  "success": true,
  "count": 10,
  "videos": [
    {
      "video_id": "abc123",
      "title": "Video Title",
      "channel_name": "Channel Name",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 1500000,
      "thumbnail_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
      "upload_date": "2026-03-20",
      "url": "https://www.youtube.com/watch?v=abc123",
      "duration": 612,
      "subscriber_count": 85000,
      "similarity_score": 78
    }
  ]
}
```

---

## Rate Limits

| Plan | Requests/min | Daily limit |
|------|-------------|-------------|
| Professional | 30 | 1,000 |
| Ultimate | 60 | 5,000 |

Rate limit headers are included in every response:
- `X-RateLimit-Limit` — max requests per window
- `X-RateLimit-Remaining` — requests left
- `X-RateLimit-Reset` — seconds until window resets

---

## Credits

| Feature | Cost |
|---------|------|
| TTS Generation | 1 credit per 1000 characters |
| Voice Clone | 1 credit |
| Caption Removal | 1 credit |
| Sora Watermark Removal | 2 credits |
| Image Generation | 1 credit |
| Video Generation | 2-5 credits (varies by model) |
| YouTube Scraper | 1 credit per job |
| Terminated Channel Search | Free (included with plan) |

---

## Error Codes

| Code | Meaning |
|------|---------|
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — plan upgrade required |
| 404 | Not found — resource doesn't exist |
| 429 | Rate limited — too many requests |
| 500 | Server error — try again later |

Error response format:
```json
{
  "success": false,
  "error": "Description of what went wrong"
}
```