v1 REST API for engaging social posts, smart replies, blogs, and newsletters.
Integrate supapost into your applications and workflows. Generate AI-powered posts, manage content, create images, and more -- all through a simple REST API.
https://supapost.ai/api/v1All API requests require authentication using a Bearer token in the Authorization header. API keys can be generated from the dashboard settings and are available on all plans: Free (50 req/day),Pro (500 req/day),Agency (2,000 req/day).
curl -X GET https://supapost.ai/api/v1/posts \
-H "Authorization: Bearer YOUR_API_KEY"Keep your API key secret. Do not share it in publicly accessible areas such as GitHub, client-side code, or browser requests. If a key is compromised, revoke it immediately from the dashboard.
Rate limits are applied per API key to ensure fair usage. When you exceed the limit, the API will return a 429 Too Many Requests response.
| Endpoint | Limit |
|---|---|
| Most endpoints | 60 req/min |
| Image generation | 20 req/min |
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
Errors return a JSON object with an error string and the HTTP status. Plan-tier and quota errors include extra context fields (feature, current_plan, limit, reset_at) at the top level.
{
"error": "Invalid or missing API key"
}| Status | Code | Description |
|---|---|---|
| 400 | BAD_REQUEST | Invalid request body or parameters |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 402 | PAYMENT_REQUIRED | Feature requires a paid plan; response includes feature, current_plan, required_plans |
| 404 | NOT_FOUND | Resource not found |
| 429 | RATE_LIMITED | Daily, per-minute, or monthly quota exceeded; response includes limit and reset_at |
| 500 | INTERNAL_ERROR | Something went wrong on our end |
| 502 | UPSTREAM_ERROR | AI provider rejected or errored (e.g. content policy) |
| 503 | UNAVAILABLE | Plan limits or AI service not configured. Contact support |
Click on an endpoint to expand its documentation including parameters, examples, and response formats.
/api/v1/content/generateThe primary content generation endpoint. Generate social posts, smart replies, blog articles, or newsletters from a single endpoint. Adapts AI prompts based on the content type and target platform.
| Parameter | Type | Description |
|---|---|---|
type | "social" | "reply" | "blog" | "newsletter" | The type of content to generate |
topic | string | The topic to generate content about. Required for blog and newsletter. Optional for social: omit it and the post is written from your brand settings, content pillars and saved topics, skipping subjects you have posted about recently |
originalPost | string | The comment or post to reply to (required when type is reply) |
platform | "x" | "linkedin" | "instagram" | "facebook" | Target platform (for social and reply types) |
tone | string | Override the workspace default tone |
keywords | string[] | SEO keywords (for blog type) |
targetLength | "short" | "medium" | "long" | Target length (for blog type) |
curl -X POST https://supapost.ai/api/v1/content/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "blog",
"topic": "AI in content marketing",
"keywords": ["AI", "content marketing", "automation"],
"targetLength": "medium"
}'{
"type": "blog",
"title": "Why AI-Powered Content Is the Future of Marketing",
"introduction": "In 2025, AI-generated content...",
"sections": [
{ "heading": "The Rise of AI Content", "content": "..." }
],
"conclusion": "Start leveraging AI today...",
"meta_description": "Discover how AI is transforming content marketing...",
"hashtags": ["AI", "ContentMarketing"],
"estimated_read_time": "5 min read"
}/api/v1/strategy/generateGenerate a cohesive content strategy across multiple platforms from a single topic. Returns platform-native content for each selected platform with posting recommendations.
| Parameter | Type | Description |
|---|---|---|
topic | string | The topic to build a strategy around |
platforms | string[] | Array of platforms: "x", "linkedin", "instagram", "facebook" |
tone | string | Override the workspace default tone |
curl -X POST https://supapost.ai/api/v1/strategy/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"topic": "AI in content marketing",
"platforms": ["x", "linkedin", "instagram"]
}'{
"strategy_title": "AI in Content Marketing - Multi-Platform Strategy",
"topic_angle": "How AI is democratizing high-quality content creation",
"platforms": [
{
"platform": "x",
"content_type": "social_post",
"content": "AI isn't replacing writers. It's giving every founder a writing partner...",
"rationale": "Short, punchy takes perform best on X",
"best_time": "Tuesday 9am EST",
"hashtags": ["AI", "ContentCreation"]
},
{
"platform": "linkedin",
"content_type": "social_post",
"content": "I've been using AI to create content for 6 months. Here's what changed...",
"rationale": "Personal stories drive LinkedIn engagement",
"best_time": "Wednesday 8am EST",
"hashtags": ["ContentMarketing", "AI"]
}
]
}/api/v1/content/repurposeTake existing content from one platform and adapt it for another. Transforms format, length, and style while preserving the core message.
| Parameter | Type | Description |
|---|---|---|
sourceContent | string | The original content to repurpose |
sourcePlatform | string | The platform the content was written for |
targetPlatform | "x" | "linkedin" | "instagram" | "facebook" | "general" | The target platform |
targetType | "social_post" | "thread" | "blog_post" | "newsletter" | The target content type |
tone | string | Override tone for the target |
curl -X POST https://supapost.ai/api/v1/content/repurpose \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sourceContent": "A long blog post about AI in marketing...",
"sourcePlatform": "blog",
"targetPlatform": "x",
"targetType": "social_post"
}'{
"sourcePlatform": "blog",
"targetPlatform": "x",
"targetType": "social_post",
"content": "Most founders think AI content is generic. They're using it wrong...",
"hashtags": ["AI", "ContentMarketing"],
"variations": ["AI content doesn't have to sound robotic. Here's the secret..."]
}/api/v1/blogsRetrieve a paginated list of blog posts in your workspace.
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: "draft", "scheduled", "posted", "archived" |
limit | number | Number of blogs to return (default: 20, max: 100) |
offset | number | Offset for pagination (default: 0) |
curl -X GET "https://supapost.ai/api/v1/blogs?status=draft" \
-H "Authorization: Bearer YOUR_API_KEY"{
"blogs": [{ "id": "...", "title": "My Blog Post", "content": "...", "content_type": "blog_post", "meta_description": "...", "status": "draft" }],
"total": 12,
"limit": 20,
"offset": 0
}/api/v1/blogsCreate a new blog post in your workspace.
| Parameter | Type | Description |
|---|---|---|
title | string | Blog post title |
content | string | Blog post content (supports markdown) |
meta_description | string | SEO meta description (max 160 chars) |
hashtags | string[] | Tags for the blog post |
status | string | Post status (default: "draft") |
curl -X POST https://supapost.ai/api/v1/blogs \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Why AI Changes Everything",
"content": "# Introduction\n\nAI is transforming...",
"meta_description": "Discover how AI is reshaping content creation"
}'{
"blog": { "id": "...", "title": "My Blog Post", "content": "...", "content_type": "blog_post", "platform": "general", "status": "draft" }
}/api/v1/newslettersRetrieve a paginated list of newsletters in your workspace.
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status |
limit | number | Number to return (default: 20) |
offset | number | Offset for pagination |
curl -X GET "https://supapost.ai/api/v1/newsletters" \
-H "Authorization: Bearer YOUR_API_KEY"{
"newsletters": [{ "id": "...", "subject_line": "This Week in AI", "content": "...", "content_type": "newsletter", "status": "draft" }],
"total": 5,
"limit": 20,
"offset": 0
}/api/v1/newslettersCreate a new newsletter in your workspace.
| Parameter | Type | Description |
|---|---|---|
subject_line | string | Email subject line (max 100 chars) |
content | string | Newsletter body content |
title | string | Internal title (defaults to subject line) |
curl -X POST https://supapost.ai/api/v1/newsletters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject_line": "This Week in AI: 3 Tools You Need",
"content": "Hey there! Here are this week\'s top AI tools..."
}'{
"newsletter": { "id": "...", "subject_line": "This Week in AI", "content": "...", "content_type": "newsletter", "status": "draft" }
}/api/v1/usageGet your current billing period usage statistics and plan limits.
curl -X GET https://supapost.ai/api/v1/usage \
-H "Authorization: Bearer YOUR_API_KEY"{
"plan": "pro",
"period": { "start": "2025-01-01", "end": "2025-01-31" },
"usage": {
"posts_generated": 45,
"blogs_generated": 8,
"newsletters_generated": 3,
"images_generated": 12,
"ai_requests": 68
},
"limits": {
"max_posts_per_month": 100,
"api_requests_per_day": 500,
"image_generation": true,
"scheduling": true
}
}/api/v1/workspacesList all workspaces the authenticated user has access to, including their role in each.
curl -X GET https://supapost.ai/api/v1/workspaces \
-H "Authorization: Bearer YOUR_API_KEY"{
"workspaces": [
{ "id": "...", "name": "My Brand", "slug": "my-brand", "role": "owner" },
{ "id": "...", "name": "Client X", "slug": "client-x", "role": "admin" }
]
}/api/v1/posts/generateGenerate an AI-powered post based on a topic. Returns the generated content along with variations, suggested hashtags, and an optional thread breakdown.
| Parameter | Type | Description |
|---|---|---|
topic | string | The topic or idea to generate a post about |
tone | string | The tone of the generated post (e.g. "professional", "casual", "bold") |
type | "single" | "thread" | Whether to generate a single post or a thread. Defaults to single |
curl -X POST https://supapost.ai/api/v1/posts/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"topic": "AI and creativity",
"tone": "professional",
"type": "thread"
}'{
"content": "Most people think AI replaces creativity. Here's why it actually amplifies it...",
"variations": [
"AI doesn't replace creativity - it supercharges it. Here's the proof...",
"The myth: AI kills creativity. The truth? It's your biggest creative advantage."
],
"hashtags": ["#AI", "#Creativity", "#ContentCreation"],
"thread": [
"Most people think AI replaces creativity. Here's why it actually amplifies it... (1/4)",
"First, AI handles the heavy lifting - research, outlines, and drafts - so you can focus on what matters: your unique perspective. (2/4)",
"Second, it generates dozens of variations in seconds. Your job? Pick the best one and make it yours. (3/4)",
"The creators winning in 2025 aren't avoiding AI. They're using it as a creative multiplier. Start today. (4/4)"
]
}/api/v1/postsRetrieve a paginated list of posts in your workspace. Filter by status and control pagination with limit and offset.
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by post status: "draft", "scheduled", "posted", "archived" |
content_type | string | Filter by content type: "social_post", "thread", "blog_post", "newsletter" |
platform | string | Filter by platform: "x", "linkedin", "instagram", "facebook" |
limit | number | Number of posts to return (default: 20, max: 100) |
offset | number | Number of posts to skip for pagination (default: 0) |
curl -X GET "https://supapost.ai/api/v1/posts?status=draft&limit=20&offset=0" \
-H "Authorization: Bearer YOUR_API_KEY"{
"posts": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "AI is transforming how we create content...",
"post_type": "single",
"content_type": "social_post",
"platform": "x",
"status": "draft",
"hashtags": ["AI", "Content"],
"scheduled_at": null,
"created_at": "2026-04-15T10:30:00Z",
"updated_at": "2026-04-15T10:30:00Z"
}
],
"total": 42,
"limit": 20,
"offset": 0
}/api/v1/postsCreate a new post in your workspace. Optionally schedule it for a future date.
| Parameter | Type | Description |
|---|---|---|
content | string | The post body. Server does not truncate; respect platform limits client-side (X = 280 chars) |
post_type | string | Post type: "single" or "thread". Defaults to "single" |
content_type | string | Internal content classification: "social_post", "thread", "blog_post", "newsletter". Defaults to "social_post" |
platform | string | Target platform: "x", "linkedin", "instagram", "facebook". Defaults to "x" |
title | string | Optional title (used for blog/newsletter content_type) |
meta_description | string | Optional SEO meta description for blog posts |
subject_line | string | Newsletter subject line (when content_type is newsletter) |
hashtags | string[] | Array of hashtags to include |
image_url | string | Public http(s) URL of an image to attach |
status | string | Post status: "draft" or "scheduled". Defaults to "draft". Note: "scheduled" stores the planned date but does not auto-publish — connect your own scheduler via the API to ship at scheduled_at |
scheduled_at | string | ISO 8601 date string for scheduling. Required when status is scheduled |
curl -X POST https://supapost.ai/api/v1/posts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Building in public is the best growth hack for startups.",
"hashtags": ["#BuildInPublic", "#Startups"],
"status": "scheduled",
"scheduled_at": "2025-02-01T09:00:00Z"
}'{
"post": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "Building in public is the best growth hack for startups.",
"post_type": "single",
"content_type": "social_post",
"platform": "x",
"status": "scheduled",
"hashtags": ["BuildInPublic", "Startups"],
"scheduled_at": "2026-05-01T09:00:00Z",
"created_at": "2026-04-15T10:30:00Z",
"updated_at": "2026-04-15T10:30:00Z"
}
}/api/v1/posts/:idRetrieve a single post by its ID.
curl -X GET https://supapost.ai/api/v1/posts/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY"{
"post": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "Building in public is the best growth hack for startups.",
"post_type": "single",
"content_type": "social_post",
"platform": "x",
"status": "draft",
"hashtags": ["BuildInPublic"],
"scheduled_at": null,
"created_at": "2026-04-15T10:30:00Z",
"updated_at": "2026-04-15T10:30:00Z"
}
}/api/v1/posts/:idUpdate an existing post. Only include the fields you want to change.
| Parameter | Type | Description |
|---|---|---|
content | string | Updated post content |
post_type | string | Updated post type: "single" or "thread" |
hashtags | string[] | Updated hashtags array |
image_url | string | Public http(s) URL of an image to attach (400 if not a valid URL) |
image_prompt | string | Optional prompt used when the image was AI-generated (for record-keeping) |
status | string | Updated status: "draft", "scheduled", "posted", or "archived". Note: status="scheduled" stores the planned date but does not auto-publish |
scheduled_at | string | Updated scheduled date (ISO 8601) |
curl -X PATCH https://supapost.ai/api/v1/posts/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Updated: Building in public is the ultimate growth strategy.",
"status": "scheduled",
"scheduled_at": "2025-02-01T09:00:00Z"
}'{
"post": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "Updated: Building in public is the ultimate growth strategy.",
"post_type": "single",
"content_type": "social_post",
"platform": "x",
"status": "scheduled",
"hashtags": ["BuildInPublic", "Growth"],
"scheduled_at": "2026-05-01T09:00:00Z",
"created_at": "2026-04-15T10:30:00Z",
"updated_at": "2026-04-16T08:00:00Z"
}
}/api/v1/posts/:idPermanently delete a post by its ID.
curl -X DELETE https://supapost.ai/api/v1/posts/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY"{
"success": true
}/api/v1/images/generateGenerate an AI image to complement your posts. Images are square. Returns a permanent Supabase-hosted image URL; falls back to the provider's short-lived URL only if Supabase persistence fails.
| Parameter | Type | Description |
|---|---|---|
prompt | string | A description of the image to generate (max 1000 characters) |
curl -X POST https://supapost.ai/api/v1/images/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A futuristic workspace with holographic screens showing social media analytics"
}'{
"image_url": "https://<project>.supabase.co/storage/v1/object/public/brand-assets/.../image.png"
}/api/v1/templatesRetrieve all available post templates, including system templates and workspace-specific templates.
curl -X GET https://supapost.ai/api/v1/templates \
-H "Authorization: Bearer YOUR_API_KEY"{
"templates": [
{
"id": "t-001",
"name": "Hook + Value Thread",
"description": "Start with a bold hook, then deliver value in a thread",
"content": "{{hook}}\n\nHere's what most people don't know:\n\n1. {{point_1}}\n2. {{point_2}}\n3. {{point_3}}\n\nBookmark this for later.",
"category": "thread_starter",
"is_system": true,
"tags": ["engagement", "thread"],
"usage_count": 1250
}
]
}/api/v1/topics/suggestGet AI-generated topic suggestions based on your workspace settings, content pillars, and industry. Great for content planning.
| Parameter | Type | Description |
|---|---|---|
count | number | Number of topics to suggest (default: 10, max: 20) |
curl -X POST https://supapost.ai/api/v1/topics/suggest \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"count": 5
}'{
"topics": [
{
"title": "Why most startups fail at content marketing",
"description": "Explore the common pitfalls of startup content strategies and how to avoid them with a data-driven approach.",
"content_pillar": "Marketing"
},
{
"title": "The compound effect of daily posting",
"description": "How consistent daily posting on X leads to exponential audience growth over 90 days.",
"content_pillar": "Growth"
}
]
}Send your API key as a Bearer token in the Authorization header of every request. Create keys in the dashboard under Settings then API Keys. Each key is scoped to one workspace and stored as a SHA-256 hash, and revoking a key takes effect immediately across all clients.
https://supapost.ai/api/v1 is the base URL for every endpoint. All requests are HTTPS, all request and response bodies are JSON, and paths are appended directly, so content generation lives at https://supapost.ai/api/v1/content/generate.
The API returns HTTP 429 with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers telling you the cap and when it resets. Requests over the limit are rejected, never billed as overage. Daily limits are 50 on Free, 500 on Pro, and 2,000 on Agency.
Four: social posts, replies, blog articles, and newsletters. Set type in the request body, and for social content set platform to x, linkedin, instagram, or facebook. Output is formatted for the target platform, so length, hooks, and hashtag handling differ per platform.
No. Brand voice, tone, industry, audience, and content pillars are stored on the workspace the API key belongs to, and every request inherits them. Pass tone or custom instructions in the body only when you want to override the stored profile for one call.
There are none, and none are needed. The API is plain REST over HTTPS with Bearer auth and JSON bodies, so the built-in HTTP client of any language works. The same call runs from curl, fetch, requests, an n8n HTTP Request node, or an AI agent tool.