API Reference

Complete reference for all GenerateBot API endpoints. All requests use JSON and require Bearer token authentication.

Authentication

All API requests must include your API key in the Authorization header. You can create API keys in your dashboard under Settings > API Keys.

Authorization: Bearer your-api-key-here

Rate Limits

Plan	Requests per minute	Concurrent pipelines
Free	10	1
Pro	60	5
Enterprise	300	20

Error Format

All errors return a consistent JSON structure with an HTTP status code, error type, and human-readable message.

{
  "error": {
    "code": "insufficient_credits",
    "message": "You need 100 credits for this operation. Current balance: 50."
  },
  "requestId": "req_abc123"
}

Endpoint Overview

Method	Endpoint	Description	Credits
POST	`/api/v1/agents/news-aggregator`	Search for trending articles on any topic	10
POST	`/api/v1/pipelines`	Start content generation from a URL or topic	100
GET	`/api/v1/pipelines`	List all pipeline runs	Free
GET	`/api/v1/pipelines/{runId}`	Get status and results of a pipeline run	Free
POST	`/api/v1/videos`	Generate a branded video reel	200
GET	`/api/v1/videos/{jobId}`	Get status and URL of a video job	Free
POST	`/api/v1/enrich/internal-links`	Add internal links to article content	20
POST	`/api/v1/enrich/images`	Match and inject images into article sections	20
POST	`/api/v1/agents/script-generator`	Generate a video script from a topic	15
POST	`/api/v1/agents/reddit-replier`	Generate helpful Reddit replies that reference your brand	10
POST	`/api/v1/agents/business-profile-generator`	Generate a Business Profile from your website URL	5
POST	`/api/v1/agents/brand-voice-rewriter`	Rewrite any text in your brand voice	5
POST	`/api/v1/agents/ai-image-generator`	Generate an AI image from a text prompt	10
POST	`/api/v1/content`	Save content as a draft	Free
GET	`/api/v1/content`	List all saved content items	Free
GET	`/api/v1/content/{id}`	Get a specific content item with full content data	Free
PATCH	`/api/v1/content/{id}`	Update a content item	Free
DELETE	`/api/v1/content/{id}`	Delete a content item	Free
GET	`/api/v1/social/accounts`	List connected social media accounts	Free
POST	`/api/v1/social/post`	Publish content to one or more social platforms	Free
GET	`/api/v1/social/history`	View posting history and status	Free
GET	`/api/v1/cms/accounts`	List connected CMS platforms	Free
POST	`/api/v1/cms/publish`	Publish an article to a connected CMS	Free
GET	`/api/v1/cms/history`	View CMS publishing history	Free
GET	`/api/v1/credits`	Get current credit balance	Free
GET	`/api/v1/credits/transactions`	List credit transaction history	Free

Search

POST/api/v1/agents/news-aggregator10 credits

Search for trending articles matching your topic. Returns article titles, summaries, source URLs, and metadata. Use the best URL from results as input to POST /api/v1/pipelines.

Request Body

{
  "topic": "AI startups funding 2026",
  "category": "technology",
  "searchConfig": {
    "resultLimit": 10,
    "countryCode": "us",
    "freshness": "pw",
    "searchBreadth": "wide"
  }
}

Response

{
  "articles": [
    {
      "url": "https://example.com/ai-startup-funding",
      "title": "AI Startup Raises $50M Series B",
      "description": "A San Francisco-based AI company has secured $50M in Series B funding...",
      "source": "TechCrunch",
      "publishedAt": "2026-03-22T10:30:00Z",
      "category": "technology",
      "categoryConfidence": 0.95
    }
  ],
  "summary": {
    "totalArticles": 10,
    "articlesByCategory": {
      "technology": 10
    },
    "sources": [
      "TechCrunch",
      "Reuters"
    ]
  },
  "creditsConsumed": 10
}

Content Generation

POST/api/v1/pipelines100 credits

Start a content generation pipeline. Use 'content-analyzer' with a URL, or 'full-pipeline' with a topic query. This is asynchronous - poll GET /api/v1/pipelines/{runId} until status is 'completed'. Do NOT call POST again - each call charges credits.

Request Body

{
  "pipelineType": "content-analyzer",
  "url": "https://example.com/article-about-ai",
  "market": "us",
  "businessProfile": {
    "companyName": "Acme Corp",
    "brandVoice": "professional",
    "targetAudience": "startup founders"
  }
}

Response

{
  "success": true,
  "data": {
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "pipelineType": "content-analyzer",
    "status": "running",
    "creditsConsumed": 100,
    "statusUrl": "/api/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "requestId": "req_abc123"
}

GET/api/v1/pipelines

List all your pipeline runs with their current status. Supports pagination and filtering.

Query Parameters

Name	Type	Description
`status`	string	Filter: pending, running, completed, failed, partial
`pipelineType`	string	Filter by pipeline type
`limit`	number	Results per page (default: 10, max: 50)
`offset`	number	Pagination offset (default: 0)

Response

{
  "success": true,
  "data": {
    "runs": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "pipelineType": "content-analyzer",
        "status": "completed",
        "progressPercentage": 100,
        "createdAt": "2026-03-22T10:30:00Z",
        "completedAt": "2026-03-22T10:32:15Z",
        "creditsConsumed": 100
      }
    ],
    "pagination": {
      "total": 42,
      "limit": 10,
      "offset": 0
    }
  },
  "requestId": "req_abc123"
}

GET/api/v1/pipelines/{runId}

Get the status and results of a specific pipeline run. Poll every 10 seconds until status is 'completed'. Results include articles, social posts, scripts, carousels, and images.

Response

{
  "status": "completed",
  "results": {
    "data": {
      "agents": {
        "aiContentGenerator": {
          "generatedContent": {
            "articles": [
              {
                "title": "How AI Changes the Landscape",
                "introduction": "A new model has been released...",
                "sections": [
                  {
                    "heading": "Key Changes",
                    "content": "..."
                  }
                ],
                "wordCount": 1200
              }
            ],
            "linkedInPosts": [
              {
                "intro": "Exciting news in AI...",
                "mainContent": "Here is what this means...",
                "callToAction": "Follow for more",
                "hashtags": [
                  "#AI",
                  "#TechNews"
                ]
              }
            ],
            "instagramPosts": [
              {
                "caption": "This is a game-changer...",
                "hashtags": [
                  "#AI"
                ],
                "imageTextOverlay": "The Future of AI"
              }
            ]
          }
        },
        "scriptGenerator": {
          "scripts": [
            {
              "hook": "This just changed everything!",
              "platform": "tiktok",
              "mainContent": [
                {
                  "scene": 1,
                  "voiceOver": "A new model just released...",
                  "textOverlay": "Breaking News"
                }
              ],
              "callToAction": "Follow for more!",
              "hashtags": [
                "#AI"
              ]
            }
          ]
        },
        "imageFinder": {
          "foundImages": [
            {
              "imageUrl": "https://cdn.example.com/img1.jpg",
              "altText": "AI processor chip",
              "suggestedUse": "hero"
            }
          ]
        },
        "carouselGenerator": {
          "carousel": {
            "slides": [
              {
                "slideNumber": 1,
                "text": "Key takeaway from the article"
              },
              {
                "slideNumber": 2,
                "text": "Supporting data point"
              }
            ]
          }
        }
      }
    },
    "totalImagesFound": 30,
    "totalContentItems": 5
  },
  "requestId": "req_abc123"
}

Video Creation

POST/api/v1/videos200 credits

Create a branded video reel from a script and slides. Supports per-slide styling, AI voiceover, text overlays, and multiple video frameworks. This is asynchronous - poll GET /api/v1/videos/{jobId} every 5 seconds.

Request Body

{
  "script": "Here is what happened. The impact is significant. Follow for more!",
  "hook": "Breaking news you need to know!",
  "slides": [
    {
      "text": "Key takeaway from the article",
      "imageUrl": "https://cdn.example.com/img1.jpg",
      "highlight": "Key takeaway",
      "imageMode": "background_with_overlays",
      "fontSize": 64,
      "textPosition": "center"
    },
    {
      "text": "Supporting point with context",
      "imageUrl": "https://cdn.example.com/img2.jpg",
      "highlight": "Supporting",
      "imageMode": "background_with_overlays"
    }
  ],
  "framework": "hormozi-documentation",
  "voiceId": "your-elevenlabs-voice-id",
  "ttsModel": "eleven_v3",
  "speedFactor": 1,
  "watermark": "@ YourBrand",
  "cta": {
    "text": "Follow for more",
    "url": "https://example.com"
  },
  "style": {
    "accentColor": "#FF5500",
    "captionStyle": "outlined",
    "captionPosition": "lower-third",
    "fontSize": 48,
    "colorGrade": "warm",
    "filmGrain": {
      "enabled": true,
      "opacity": 0.025,
      "fps": 8
    }
  }
}

Response

{
  "success": true,
  "data": {
    "jobId": "vid_x7y8z9a0-b1c2-3d4e-f5g6-h7i8j9k0l1m2",
    "status": "queued",
    "creditsConsumed": 200,
    "statusUrl": "/api/v1/videos/vid_x7y8z9a0-b1c2-3d4e-f5g6-h7i8j9k0l1m2"
  },
  "requestId": "req_abc123"
}

GET/api/v1/videos/{jobId}

Get the status and download URL of a video generation job. Poll every 5 seconds until status is 'completed' or 'failed'.

Response

{
  "success": true,
  "data": {
    "jobId": "vid_x7y8z9a0-b1c2-3d4e-f5g6-h7i8j9k0l1m2",
    "status": "completed",
    "videoUrl": "https://cdn.generatebot.com/videos/rendered/x7y8z9a0.mp4",
    "thumbnailUrl": "https://cdn.generatebot.com/videos/thumbs/x7y8z9a0.jpg",
    "durationSeconds": 32,
    "createdAt": "2026-03-22T10:35:00Z",
    "completedAt": "2026-03-22T10:37:45Z"
  },
  "requestId": "req_abc123"
}

Content Enrichment

POST/api/v1/enrich/internal-links20 credits

Enrich an article with internal links by matching content against your sitemap. Pass the article object from pipeline results directly as the 'article' field.

Request Body

{
  "article": {
    "title": "Complete Guide to Content Marketing in 2025",
    "introduction": "Content marketing is a strategic approach...",
    "sections": [
      {
        "heading": "SEO Best Practices",
        "content": "Search engine optimization plays a critical role..."
      }
    ]
  },
  "businessProfile": {
    "sitemapUrl": "https://myblog.com/sitemap.xml",
    "websiteUrl": "https://myblog.com",
    "companyName": "My Blog"
  }
}

Response

{
  "success": true,
  "data": {
    "enrichedArticle": {
      "title": "Complete Guide to Content Marketing in 2025",
      "introduction": "Content marketing is a strategic approach...",
      "sections": [
        {
          "heading": "SEO Best Practices",
          "content": "...<a href=\"https://myblog.com/seo-guide\">Search engine optimization</a> plays a critical role..."
        }
      ]
    },
    "linksAdded": 3,
    "linkedPages": [
      {
        "url": "https://myblog.com/seo-guide",
        "anchorText": "Search engine optimization",
        "section": "SEO Best Practices"
      }
    ]
  },
  "requestId": "req_abc123"
}

POST/api/v1/enrich/images20 credits

Match and inject relevant images into article sections based on content relevance.

Request Body

{
  "article": {
    "title": "The Rise of Electric Vehicles",
    "sections": [
      {
        "heading": "Market Growth",
        "content": "The EV market has grown by 35%..."
      }
    ]
  },
  "images": [
    {
      "imageUrl": "https://images.unsplash.com/photo-ev-charging",
      "altText": "Electric vehicle charging",
      "suggestedUse": "hero"
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "matches": [
      {
        "sectionIndex": 0,
        "heading": "Market Growth",
        "imageUrl": "https://images.unsplash.com/photo-ev-charging",
        "altText": "Electric vehicle charging",
        "relevanceScore": 0.92
      }
    ],
    "heroImage": {
      "imageUrl": "https://images.unsplash.com/photo-ev-charging",
      "altText": "Electric vehicle charging"
    }
  },
  "requestId": "req_abc123"
}

Content Tools

POST/api/v1/agents/script-generator15 credits

Generate a video script from a topic, structured with hooks, scenes, and calls to action.

Request Body

{
  "topic": "Why cold showers boost productivity",
  "scriptType": "tiktok",
  "tone": "energetic",
  "targetLength": 60
}

Response

{
  "success": true,
  "data": {
    "script": {
      "hook": "I took cold showers for 30 days and here is what happened...",
      "body": "Day 1: I hated it. By day 7, something changed...",
      "callToAction": "Try it for 7 days. Follow for more.",
      "estimatedDuration": 58,
      "hashtags": [
        "#coldshower",
        "#productivity",
        "#morningroutine"
      ]
    }
  },
  "requestId": "req_abc123"
}

POST/api/v1/agents/reddit-replier10 credits

Generate helpful, authentic Reddit replies that naturally reference your brand.

Request Body

{
  "redditPostUrl": "https://reddit.com/r/marketing/comments/abc123/best_tools/",
  "businessContext": "We help businesses automate content creation",
  "tone": "helpful"
}

Response

{
  "success": true,
  "data": {
    "replies": [
      {
        "text": "Great question! From our experience, the biggest time savings come from automating the research phase...",
        "subreddit": "r/marketing",
        "confidence": 0.85
      }
    ]
  },
  "requestId": "req_abc123"
}

POST/api/v1/agents/business-profile-generator5 credits

Analyze a website URL and generate a structured Business Profile including brand voice, target audience, and content themes.

Request Body

{
  "websiteUrl": "https://example.com",
  "companyName": "Example Corp"
}

Response

{
  "agent": "business-profile-generator",
  "creditsConsumed": 5,
  "data": {
    "companyName": "Example Corp",
    "industryCategory": "SaaS",
    "description": "A platform for...",
    "targetAudience": "startup founders",
    "keyProducts": [
      "Product A",
      "Product B"
    ],
    "tone": "professional but approachable",
    "brandVoice": "authoritative"
  }
}

POST/api/v1/agents/brand-voice-rewriter5 credits

Rewrite any text to match your configured brand voice while preserving the core message.

Request Body

{
  "content": "Our company has released a new product that helps with marketing.",
  "brandVoice": "casual and witty",
  "targetAudience": "startup founders",
  "companyName": "Acme Corp"
}

Response

{
  "success": true,
  "data": {
    "rewritten": "Stop spending your Tuesday writing LinkedIn posts. Our AI does it while you grab coffee.",
    "originalLength": 96,
    "rewrittenLength": 152
  },
  "requestId": "req_abc123"
}

POST/api/v1/agents/ai-image-generator10 credits

Generate an AI image from a text prompt. Returns a URL to the generated image.

Request Body

{
  "prompt": "A modern office space with natural light, plants, and people collaborating",
  "style": "photorealistic",
  "aspectRatio": "16:9"
}

Response

{
  "success": true,
  "data": {
    "images": [
      {
        "imageUrl": "https://cdn.generatebot.com/ai-images/gen_img_456.png",
        "prompt": "A modern office space with natural light, plants, and people collaborating",
        "width": 1920,
        "height": 1080
      }
    ]
  },
  "requestId": "req_abc123"
}

Content Library

POST/api/v1/content

Save content to your library. All new content is saved as 'draft' status. Use PATCH to change status to published, scheduled, or archived.

Request Body

{
  "contentType": "linkedin",
  "title": "AI Productivity Tips - LinkedIn Post",
  "contentData": {
    "text": "I increased my team output by 3x using AI tools...",
    "hashtags": [
      "#AI",
      "#Productivity"
    ]
  },
  "tags": [
    "linkedin",
    "productivity"
  ]
}

Response

{
  "success": true,
  "data": {
    "content": {
      "id": "cnt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content_type": "linkedin",
      "title": "AI Productivity Tips - LinkedIn Post",
      "preview_text": "I increased my team output by 3x...",
      "status": "draft",
      "word_count": 68,
      "tags": [
        "linkedin",
        "productivity"
      ],
      "created_at": "2026-03-22T18:00:00Z",
      "updated_at": "2026-03-22T18:00:00Z"
    }
  },
  "requestId": "req_abc123"
}

GET/api/v1/content

List all saved content items. Does not include full contentData in list view.

Query Parameters

Name	Type	Description
`contentType`	string	Filter: linkedin, instagram, article, tiktok, script, reel
`status`	string	Filter: draft, published, scheduled, archived
`tags`	string	Comma-separated tags (must match all)
`limit`	number	Results per page (default: 10, max: 50)
`offset`	number	Pagination offset (default: 0)

Response

{
  "success": true,
  "data": {
    "content": [
      {
        "id": "cnt_a1b2c3d4",
        "content_type": "linkedin",
        "title": "AI Productivity Tips",
        "preview_text": "I increased my team output by 3x...",
        "status": "draft",
        "word_count": 68,
        "tags": [
          "linkedin",
          "productivity"
        ],
        "created_at": "2026-03-22T18:00:00Z"
      }
    ],
    "pagination": {
      "total": 15,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  },
  "requestId": "req_abc123"
}

GET/api/v1/content/{id}

Get full content detail including contentData.

Response

{
  "success": true,
  "data": {
    "content": {
      "id": "cnt_a1b2c3d4",
      "content_type": "linkedin",
      "title": "AI Productivity Tips",
      "content_data": {
        "text": "I increased my team output by 3x using AI tools...",
        "hashtags": [
          "#AI",
          "#Productivity"
        ]
      },
      "preview_text": "I increased my team output by 3x...",
      "status": "draft",
      "word_count": 68,
      "tags": [
        "linkedin",
        "productivity"
      ],
      "notes": null,
      "created_at": "2026-03-22T18:00:00Z",
      "updated_at": "2026-03-22T18:00:00Z"
    }
  },
  "requestId": "req_abc123"
}

PATCH/api/v1/content/{id}

Update content fields. At least one field must be provided. Use this to change status (draft, published, scheduled, archived).

Request Body

{
  "title": "Updated: AI Productivity Tips for 2025",
  "status": "published",
  "tags": [
    "linkedin",
    "productivity",
    "2025"
  ]
}

Response

{
  "success": true,
  "data": {
    "content": {
      "id": "cnt_a1b2c3d4",
      "content_type": "linkedin",
      "title": "Updated: AI Productivity Tips for 2025",
      "status": "published",
      "tags": [
        "linkedin",
        "productivity",
        "2025"
      ],
      "updated_at": "2026-03-22T19:00:00Z"
    }
  },
  "requestId": "req_abc123"
}

DELETE/api/v1/content/{id}

Permanently delete a content item.

Response

{
  "success": true,
  "data": {
    "deleted": true
  },
  "requestId": "req_abc123"
}

Social Media

GET/api/v1/social/accounts

List all connected social media accounts and their current status.

Response

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "sma_a1b2c3d4",
        "platform": "linkedin",
        "username": "johndoe",
        "profilePictureUrl": "https://media.licdn.com/dms/image/...",
        "isConnected": true,
        "createdAt": "2025-02-15T10:00:00Z"
      },
      {
        "id": "sma_e5f6g7h8",
        "platform": "instagram",
        "username": "johndoe_ig",
        "profilePictureUrl": "https://instagram.com/profile/...",
        "isConnected": true,
        "createdAt": "2025-02-20T14:30:00Z"
      }
    ]
  },
  "requestId": "req_abc123"
}

POST/api/v1/social/post

Publish content to connected social platforms. Requires a contentId from your content library. Supported platforms: instagram, tiktok, threads, linkedin, youtube. Content types: text, image, video, carousel, multi-image.

Request Body

{
  "contentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platforms": [
    {
      "accountId": "sma_a1b2c3d4",
      "platform": "linkedin",
      "contentType": "text",
      "text": "Just published our latest guide on sustainable architecture."
    },
    {
      "accountId": "sma_e5f6g7h8",
      "platform": "instagram",
      "contentType": "image",
      "caption": "New guide out now!",
      "hashtags": [
        "#architecture",
        "#sustainability"
      ],
      "mediaUrls": [
        "https://cdn.generatebot.com/images/arch-guide.jpg"
      ]
    }
  ]
}

Response

{
  "posted": [
    {
      "historyId": "h1234-5678",
      "platform": "linkedin",
      "contentType": "text",
      "status": "pending"
    },
    {
      "historyId": "h9876-5432",
      "platform": "instagram",
      "contentType": "image",
      "status": "pending"
    }
  ],
  "failed": [],
  "creditsConsumed": 0,
  "contentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "crossPostGroupId": "group-uuid",
  "requestId": "req_abc123"
}

GET/api/v1/social/history

View your social media posting history with delivery status.

Query Parameters

Name	Type	Description
`platform`	string	Filter: linkedin, instagram, tiktok, youtube, threads
`limit`	number	Results per page (default: 10, max: 50)
`offset`	number	Pagination offset (default: 0)

Response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "sp_a1b2c3d4",
        "platform": "linkedin",
        "content": "Just published our latest guide...",
        "status": "published",
        "postUrl": "https://www.linkedin.com/feed/update/urn:li:share:123",
        "createdAt": "2026-03-22T16:00:00Z"
      }
    ],
    "pagination": {
      "total": 23,
      "limit": 10,
      "offset": 0
    }
  },
  "requestId": "req_abc123"
}

CMS Publishing

GET/api/v1/cms/accounts

List all connected CMS platforms.

Response

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "cms_a1b2c3d4",
        "platform": "wordpress",
        "siteUrl": "https://blog.example.com",
        "siteName": "My Tech Blog",
        "isConnected": true,
        "createdAt": "2025-01-10T08:00:00Z"
      }
    ]
  },
  "requestId": "req_abc123"
}

POST/api/v1/cms/publish

Publish an article to a connected CMS. Requires a contentId from your content library.

Request Body

{
  "contentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cmsAccountId": "cms_a1b2c3d4",
  "title": "How AI Changes the Landscape",
  "content": "<h2>The Next Generation</h2><p>A new model has been released...</p>",
  "excerpt": "A new model brings significant improvements.",
  "slug": "ai-changes-landscape",
  "status": "draft"
}

Response

{
  "success": true,
  "data": {
    "published": true,
    "cmsUrl": "https://blog.example.com/?p=1234",
    "platform": "wordpress",
    "status": "draft"
  },
  "requestId": "req_abc123"
}

GET/api/v1/cms/history

View your CMS publishing history.

Response

{
  "success": true,
  "data": {
    "publications": [
      {
        "id": "pub_001",
        "contentId": "cnt_789xyz",
        "platform": "wordpress",
        "cmsUrl": "https://blog.example.com/?p=1234",
        "publishedAt": "2026-03-22T11:00:00Z",
        "status": "live"
      }
    ],
    "pagination": {
      "total": 34,
      "limit": 10,
      "offset": 0
    }
  },
  "requestId": "req_abc123"
}

Credits

GET/api/v1/credits

Get your current credit balance breakdown.

Response

{
  "total": 2450,
  "subscription": 2000,
  "oneTime": 400,
  "adminGranted": 50
}

GET/api/v1/credits/transactions

List your credit transaction history showing usage and top-ups.

Query Parameters

Name	Type	Description
`type`	string	Filter: usage, purchase, refund, bonus
`limit`	number	Results per page (default: 20, max: 100)
`offset`	number	Pagination offset (default: 0)

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_001",
        "type": "usage",
        "amount": -100,
        "description": "Content generation pipeline",
        "createdAt": "2026-03-22T10:30:00Z"
      },
      {
        "id": "txn_002",
        "type": "purchase",
        "amount": 5000,
        "description": "Monthly plan allocation",
        "createdAt": "2026-03-01T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 127,
      "limit": 20,
      "offset": 0
    }
  },
  "requestId": "req_abc123"
}