Welcome to the BOLTA API. This documentation provides everything you need to integrate with BOLTA's programmatic API and leverage our Brand Voice AI capabilities.
https://platty.boltathread.comProduction docs list https://platty.boltathread.com as the public API host. This interactive explorer uses NEXT_PUBLIC_BOLTA_SERVER_URL when set (e.g. staging).
Include your API key in the Authorization header:
Authorization: Bearer bolta_sk_your_api_key_hereAPI keys can be generated in your workspace settings:
accounts:connectConnect Accounts
Initiate OAuth connections for social accounts
accounts:readRead Accounts
View connected social accounts and metadata
agents:manageManage Agents
Create, update, delete, and manage agent principals via API
ai:generateAI Content Generation
Generate AI content with brand voice
audit:exportExport Audit Logs
Export workspace audit and activity logs
content:bulkBulk Operations
Perform bulk content operations
posts:deleteDelete Posts
Delete posts and scheduled content
posts:readRead Posts
View posts and schedules
posts:writeWrite Posts
Create and update posts (schedule, draft)
recurring:manageManage Recurring Posts
Approve and reject recurring post suggestions
review:approveApprove Reviews
Approve and route reviewed content
review:submitSubmit for Review
Submit content for approval
team:manageManage Team
Create and manage agent teammates
team:manage_keysManage Keys
Rotate and manage API keys
voice:readRead Voice Profiles
View brand voice profiles and settings
voice:writeUpdate Voice Profiles
Modify brand voice profiles and settings
workspace:adminManage Workspace Settings
Change workspace settings via API: autonomy mode, Safe Mode, posting limits. Required to PATCH workspace settings.
workspace:readRead Workspace
View workspace policy and capabilities
curl -X GET "https://platty.boltathread.com/api/v1/workspaces/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/voice/profiles/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/scheduled/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"Copy-paste-runnable snippets for the four operations you'll use most: auth, list voice profiles, generate a post, and schedule it. TypeScript, Python, and Go.
BOLTA_API_KEY. Generate one in Settings → API; it will be shown once.const BOLTA_API = "https://platty.boltathread.com";
const API_KEY = process.env.BOLTA_API_KEY!;
async function listWorkspaces() {
const res = await fetch(`${BOLTA_API}/api/v1/workspaces/`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!res.ok) {
throw new Error(`Bolta auth failed: ${res.status} ${await res.text()}`);
}
return res.json() as Promise<Array<{ id: string; name: string }>>;
}
const workspaces = await listWorkspaces();
console.log("workspace_id =", workspaces[0].id);async function listVoiceProfiles(workspaceId: string) {
const res = await fetch(
`${BOLTA_API}/api/v1/workspaces/${workspaceId}/voice/profiles/`,
{ headers: { Authorization: `Bearer ${API_KEY}` } },
);
if (!res.ok) throw new Error(await res.text());
return res.json() as Promise<Array<{ id: string; name: string; tone: Record<string, number> }>>;
}async function generatePost(workspaceId: string, voiceProfileId: string, topic: string) {
const res = await fetch(
`${BOLTA_API}/api/v1/workspaces/${workspaceId}/voice/enhanced/content/`,
{
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
voice_profile_id: voiceProfileId,
content_type: "social-post",
platform: "x",
topic,
}),
},
);
if (res.status === 429) {
const retryAfter = res.headers.get("Retry-After");
throw new Error(`Rate limited; retry after ${retryAfter}s`);
}
if (!res.ok) throw new Error(await res.text());
return res.json() as Promise<{ body: string; image_prompt?: string }>;
}async function schedulePost(workspaceId: string, opts: {
body: string;
socialAccountId: string;
publishAt: string; // ISO 8601 UTC
}) {
const res = await fetch(
`${BOLTA_API}/api/v1/workspaces/${workspaceId}/posts/schedule/`,
{
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
body: opts.body,
social_account_id: opts.socialAccountId,
publish_at: opts.publishAt,
}),
},
);
if (!res.ok) throw new Error(await res.text());
return res.json() as Promise<{ id: string; status: string }>;
}res.status === 429 and honour the Retry-After header.workspace_id and voice_profile_id — they don't change often.Z).workspace.write.Get your workspace information. The workspace ID is required for all other API calls.
/api/v1/workspacescurl -X GET "https://platty.boltathread.com/api/v1/workspaces/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Workspace",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-20T14:22:00Z"
}
]/api/v1/workspaces/{workspace_id}curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Workspace",
"description": "My workspace description",
"safe_mode": true,
"autonomy_mode": "managed",
"max_posts_per_day": 100,
"max_api_requests_per_hour": 1000,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-20T14:22:00Z",
"member_count": 5,
"accounts_count": 10
}/api/v1/workspaces/{workspace_id}/policycurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/policy/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"safe_mode": true,
"inbox_direct_scheduling": false,
"workspace_type": "team"
}/api/v1/workspaces/{workspace_id}/my-capabilitiescurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/my-capabilities/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"role": "creator",
"principal_type": "agent",
"permissions": {
"create_canvas": true,
"publish_content": false,
"approve_posts": false,
"schedule_posts": false,
"edit_posts": true
},
"allowed_actions_summary": "Create drafts, submit for review",
"forbidden_actions_summary": "Cannot approve, schedule, or publish"
}/api/v1/workspaces/{workspace_id}/updatecurl -X PATCH "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/update/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"safe_mode": true,
"autonomy_mode": "managed",
"max_posts_per_day": 150
}'{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Workspace",
"description": "My workspace description",
"safe_mode": true,
"autonomy_mode": "managed",
"max_posts_per_day": 150,
"max_api_requests_per_hour": 1000,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-02-16T14:22:00Z",
"member_count": 5,
"accounts_count": 10
}/api/v1/workspaces/{workspace_id}/quota-statuscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/quota-status/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"daily_posts": {
"limit": 100,
"used": 47,
"remaining": 53,
"percentage": 47
},
"hourly_api_requests": {
"limit": 1000,
"used": 234,
"remaining": 766,
"percentage": 23.4
},
"date": "2025-02-16",
"quota_resets_at": "2025-02-17T00:00:00Z",
"warnings": []
}/api/v1/workspaces/{workspace_id}/memberscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/members" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"members": [
{
"id": "user_123",
"email": "user@example.com",
"role": "admin",
"joined_at": "2025-01-15T10:30:00Z"
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/invitationscurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/invitations" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"email": "new.user@example.com",
"role": "editor"
}'{
"success": true,
"invitation_id": "inv_123",
"email": "new.user@example.com",
"role": "editor",
"status": "pending"
}/api/v1/workspaces/{workspace_id}/settingscurl -X PUT "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/settings" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "New Workspace Name",
"timezone": "America/New_York"
}'{
"id": "ws_123",
"name": "New Workspace Name",
"timezone": "America/New_York"
}Manage your media assets. Upload images and videos to use in your posts.
/api/v1/media/uploadcurl -X POST "https://platty.boltathread.com/api/v1/media/upload" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-F "file=@/path/to/image.jpg" \
-F "workspace_id={workspace_id}"{
"id": "media_123",
"url": "https://assets.bolta.ai/images/media_123.jpg",
"filename": "image.jpg",
"mime_type": "image/jpeg",
"size": 102400,
"created_at": "2025-01-29T10:00:00Z"
}/api/v1/workspaces/{workspace_id}/mediacurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/media" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"media": [
{
"id": "media_123",
"url": "https://assets.bolta.ai/images/media_123.jpg",
"filename": "image.jpg",
"created_at": "2025-01-29T10:00:00Z"
}
],
"count": 1,
"total": 24
}/api/v1/media/{media_id}curl -X DELETE "https://platty.boltathread.com/api/v1/media/{media_id}" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"success": true,
"message": "Media deleted successfully"
}Generate authentic content that matches your brand's unique voice
/api/v1/voice/generateai:generate permission. Make sure your API key has this permission enabled.# Profile Mode (standard)
curl -X POST "https://platty.boltathread.com/api/v1/voice/generate" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"voiceProfileId": "voice-profile-uuid",
"topics": ["personal_branding", "product_launch"],
"dateRange": {
"from": "2026-01-28T05:00:00.000Z",
"to": "2026-02-03T05:00:00.000Z"
},
"time": "14:00",
"maxPosts": "5",
"postContentSize": "standard",
"context": "Write about our latest feature launch"
}'
# Scratch Mode (no profile required)
curl -X POST "https://platty.boltathread.com/api/v1/voice/generate" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"businessName": "Kingdom Fitness",
"niche": "gym fitness studio",
"context": "Community-focused gym. Simple, no-frills strength training. Local, authentic, no corporate feel.",
"tone": "authentic",
"topics": ["fitness", "community", "motivation"],
"dos": ["Sound like a real gym owner", "Reference local community", "Be specific"],
"donts": ["Excessive emojis", "Corporate buzzwords", "Generic marketing speak"],
"dateRange": {
"from": "2026-01-28T05:00:00.000Z",
"to": "2026-02-03T05:00:00.000Z"
},
"time": "14:00",
"maxPosts": "7"
}'{
"status": "processing",
"task_id": "abc123-def456-ghi789",
"message": "Content generation started in background. Use task_id to check status.",
"check_status_url": "/api/v1/posts/bulk/{task_id}/status/"
}Generate voice-enhanced replies that match your brand's tone for responding to comments and messages.
/api/v1/voice/replycurl -X POST "https://platty.boltathread.com/api/v1/voice/reply" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"user_message": "Love this product! When are you launching the new features?",
"username": "@customer123",
"account_id": "880e8400-e29b-41d4-a716-446655440003",
"platform": "twitter"
}'{
"success": true,
"reply": "Thanks so much for the love! 💜 New features are dropping next month - stay tuned for some exciting updates! 🚀",
"metadata": {
"platform": "twitter",
"character_count": 112,
"context_detected": "customer_inquiry",
"sentiment": "positive"
}
}Manage your brand voice profiles programmatically. Create, update, and delete voice profiles to maintain consistent brand communication.
/api/v1/workspaces/{workspace_id}/voice/profilescurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/voice/profiles/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"profiles": [
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"name": "Company Brand Voice",
"description": "Our main brand voice profile",
"tone": "professional",
"is_default": true,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-20T14:22:00Z"
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/voice/profilescurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/voice/profiles/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Casual Brand Voice",
"description": "A friendly, conversational tone for social media",
"tone": "casual",
"personality_traits": ["friendly", "approachable", "witty"],
"is_default": false
}'{
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "Casual Brand Voice",
"description": "A friendly, conversational tone for social media",
"tone": "casual",
"personality_traits": [
"friendly",
"approachable",
"witty"
],
"is_default": false,
"created_at": "2025-01-28T10:30:00Z"
}/api/v1/workspaces/{workspace_id}/voice/profiles/{profile_id}curl -X PUT "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/voice/profiles/{profile_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Brand Voice",
"tone": "professional"
}'{
"id": "660e8400-e29b-41d4-a716-446655440001",
"name": "Updated Brand Voice",
"tone": "professional",
"updated_at": "2025-01-28T11:00:00Z"
}/api/v1/workspaces/{workspace_id}/voice/profiles/{profile_id}curl -X DELETE "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/voice/profiles/{profile_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"success": true,
"message": "Voice profile deleted successfully"
}Manage Business DNA profiles to align content generation with brand values, aesthetics, and identity.
/api/v1/workspaces/{workspace_id}/dnacurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/dna/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Tech Startup DNA",
"website_url": "https://example.com",
"brand_values": ["Innovation", "Speed", "Reliability"]
}'{
"id": "dna_123",
"name": "Tech Startup DNA",
"status": "processing_extraction",
"created_at": "2025-01-29T10:00:00Z"
}/api/v1/workspaces/{workspace_id}/dnacurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/dna/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"profiles": [
{
"id": "dna_123",
"name": "Tech Startup DNA",
"is_active": true
}
]
}/api/v1/workspaces/{workspace_id}/dna/extractcurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/dna/extract/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"name": "Extracted DNA"
}'{
"success": true,
"dna": {
"id": "dna_123",
"name": "Extracted DNA"
}
}Create, read, update, and delete posts. Manage your content programmatically for scheduling and automation.
Every post has a status field. The API returns and accepts status in PascalCase (e.g. Scheduled, not scheduled). Use the status query parameter when listing posts to filter by one of these values.
| Status | Description |
|---|---|
| Draft | Post is not scheduled; content can be edited freely. |
| Scheduled | Post has a scheduled_time and will be published at that time. |
| Published | Post has been successfully published to the connected platform(s). |
| Failed | Publishing was attempted but failed (e.g. token expired, platform error). Check failure_reason or publication status for details. |
| Pending Approval | (Teams) Post is awaiting review before it can be scheduled. |
| Needs Revision | (Teams) Reviewer requested changes; author should update the post. |
| Approved | (Teams) Post was approved and can be scheduled. |
| Rejected | (Teams) Post was rejected and will not be published. |
| Queued | Post is in the publish queue, waiting to be sent. |
| Processing | Post is currently being published. |
| Ready for Scheduling | Post passed checks and is ready to be scheduled (e.g. after approval or validation). |
Common flows: Create with Draft or Scheduled; list/filter by status; responses always include the current status. Team workspaces may use the approval statuses (Pending Approval, Approved, Needs Revision, Rejected) for review workflows.
/api/v1/workspaces/{workspace_id}/postscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/?status=Scheduled&platform=twitter&start_date=2025-01-01&end_date=2025-02-01" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"posts": [
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"content": "Check out our latest update!",
"platform": "twitter",
"scheduled_at": "2025-01-30T14:00:00Z",
"status": "Scheduled"
}
],
"count": 1,
"total": 15,
"has_more": true,
"pagination": {
"page": 1,
"limit": 50,
"total": 15,
"has_next": false,
"has_previous": false
}
}/api/v1/postscurl -X POST "https://platty.boltathread.com/api/v1/posts/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"status": "Scheduled",
"scheduled_time": "2025-02-01T14:00:00Z",
"accounts": ["880e8400-e29b-41d4-a716-446655440003"],
"contents": [
{
"content": "Exciting news! Check out our latest update 🚀",
"index": 0,
"media": []
}
],
"tags": ["announcement"]
}'{
"id": "990e8400-e29b-41d4-a716-446655440004",
"status": "Scheduled",
"scheduled_time": "2025-02-01T14:00:00Z",
"contents": [
{
"content": "Exciting news! Check out our latest update 🚀",
"index": 0
}
],
"created_at": "2025-01-28T10:30:00Z"
}/api/v1/posts/{post_id}curl -X GET "https://platty.boltathread.com/api/v1/posts/{post_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"id": "990e8400-e29b-41d4-a716-446655440004",
"content": "Exciting news! Check out our latest update 🚀",
"platform": "twitter",
"status": "Scheduled",
"scheduled_at": "2025-02-01T14:00:00Z",
"account": {
"id": "880e8400-e29b-41d4-a716-446655440003",
"username": "@mycompany",
"platform": "twitter"
},
"created_at": "2025-01-28T10:30:00Z",
"updated_at": "2025-01-28T10:30:00Z"
}/api/v1/posts/{post_id}curl -X PUT "https://platty.boltathread.com/api/v1/posts/{post_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"content": "Updated content with better messaging! 🎉",
"scheduled_at": "2025-02-02T10:00:00Z"
}'{
"id": "990e8400-e29b-41d4-a716-446655440004",
"content": "Updated content with better messaging! 🎉",
"status": "Scheduled",
"scheduled_at": "2025-02-02T10:00:00Z",
"updated_at": "2025-01-28T11:00:00Z"
}/api/v1/posts/{post_id}curl -X DELETE "https://platty.boltathread.com/api/v1/posts/{post_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"success": true,
"message": "Post deleted successfully"
}/api/v1/workspaces/{workspace_id}/posts/scheduledcurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/scheduled/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"posts": [
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"content": "Check out our latest update!",
"platform": "twitter",
"scheduled_at": "2025-01-30T14:00:00Z",
"status": "Scheduled",
"account_id": "880e8400-e29b-41d4-a716-446655440003"
}
],
"count": 1,
"total": 1
}/api/v1/workspaces/{workspace_id}/posts/{post_id}/schedulecurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/{post_id}/schedule/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"time": "2025-02-15T14:00:00Z"
}'{
"post_id": "990e8400-e29b-41d4-a716-446655440004",
"status": "Scheduled",
"scheduled_time": "2025-02-15T14:00:00Z"
}/api/v1/workspaces/{workspace_id}/posts/{post_id}/publishcurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/{post_id}/publish/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"post_id": "990e8400-e29b-41d4-a716-446655440004",
"status": "Queued",
"message": "Publishing initiated"
}Create and manage marketing campaigns to organize your content and track performance.
/api/v1/campaignscurl -X POST "https://platty.boltathread.com/api/v1/campaigns" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"name": "Summer Sale 2025",
"description": "Q3 promotional campaign",
"start_date": "2025-06-01T00:00:00Z",
"end_date": "2025-08-31T23:59:59Z",
"budget": 5000,
"currency": "USD"
}'{
"id": "camp_123",
"name": "Summer Sale 2025",
"status": "active",
"created_at": "2025-01-29T10:00:00Z"
}/api/v1/workspaces/{workspace_id}/campaignscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/campaigns" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"campaigns": [
{
"id": "camp_123",
"name": "Summer Sale 2025",
"status": "active"
}
],
"count": 1
}Manage platform-specific post metadata for X, Threads, LinkedIn, Facebook, Instagram, BlueSky, Mastodon, Reddit, and Discord using a single unified endpoint shape. WordPress remains on the legacy path for now.
/POST/PUT/PATCH /api/v1/posts/{post_id}/details/{platform}curl -X PATCH "https://platty.boltathread.com/api/v1/posts/{post_id}/details/{platform}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"post_type": "TEXT",
"privacy": "EVERYONE",
"enable_comments": true,
"cross_post_enabled": false
}'{
"success": true,
"status": "found",
"platform": "threads",
"post_details": {
"topic_tag": "ai",
"use_topic_tag": true
},
"is_ghost_instance": false
}/api/v1/posts/{post_id}/details/xcurl -X POST "https://platty.boltathread.com/api/v1/posts/{post_id}/details/x/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"reply_settings": "everyone",
"poll_options": ["Option A", "Option B"],
"poll_duration_minutes": 1440,
"for_super_followers_only": false
}'{
"success": true,
"platform": "x",
"post_details": {
"reply_settings": "everyone",
"poll_options": [
"Option A",
"Option B"
],
"poll_duration_minutes": 1440
},
"message": "X post details saved successfully"
}/api/v1/posts/{post_id}/details/xcurl -X PUT "https://platty.boltathread.com/api/v1/posts/{post_id}/details/x/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"reply_settings": "mentioned_users",
"for_super_followers_only": false
}'{
"success": true,
"platform": "x",
"post_details": {
"reply_settings": "mentioned_users"
},
"is_ghost_instance": false,
"message": "X post details saved successfully"
}/api/v1/posts/{post_id}/details/xcurl -X GET "https://platty.boltathread.com/api/v1/posts/{post_id}/details/x/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"success": true,
"status": "found",
"platform": "x",
"post_details": {
"reply_settings": "everyone",
"poll_options": []
},
"is_ghost_instance": false
}/api/v1/posts/{post_id}/details/threadscurl -X POST "https://platty.boltathread.com/api/v1/posts/{post_id}/details/threads/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"topic_tag": "ai",
"use_topic_tag": true,
"reply_control": "everyone"
}'{
"success": true,
"platform": "threads",
"post_details": {
"topic_tag": "ai",
"use_topic_tag": true,
"reply_control": "everyone"
},
"message": "Threads post details saved successfully"
}/api/v1/posts/{post_id}/details/threadscurl -X PUT "https://platty.boltathread.com/api/v1/posts/{post_id}/details/threads/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"topic_tag": "growth",
"use_topic_tag": true,
"is_spoiler_media": false
}'{
"success": true,
"platform": "threads",
"post_details": {
"topic_tag": "growth",
"use_topic_tag": true
},
"message": "Threads post details saved successfully"
}/api/v1/posts/{post_id}/details/threadscurl -X GET "https://platty.boltathread.com/api/v1/posts/{post_id}/details/threads/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"success": true,
"status": "found",
"platform": "threads",
"post_details": {
"topic_tag": "ai",
"use_topic_tag": true,
"reply_control": "everyone"
},
"is_ghost_instance": false
}curl -X GET "https://platty.boltathread.com/threads/post-details/{post_id}/" \
-H "Authorization: Bearer {
"success": true,
"deprecated": true,
"message": "Threads post details retrieved successfully. This endpoint is deprecated; use /api/v1/posts/{post_id}/details/threads/."
}Create multiple posts at once and track bulk operation status. Perfect for large-scale content scheduling.
/api/v1/posts/bulkcurl -X POST "https://platty.boltathread.com/api/v1/posts/bulk/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"posts": [
{
"content": "Monday motivation! 💪",
"platform": "twitter",
"account_id": "880e8400-e29b-41d4-a716-446655440003",
"scheduled_at": "2025-02-03T09:00:00Z"
},
{
"content": "Tip Tuesday: Always plan your content ahead! 📅",
"platform": "twitter",
"account_id": "880e8400-e29b-41d4-a716-446655440003",
"scheduled_at": "2025-02-04T09:00:00Z"
}
]
}'{
"task_id": "task_abc123",
"status": "processing",
"total_posts": 2,
"message": "Bulk creation started. Use the task_id to check status."
}/api/v1/posts/bulk/{task_id}/statuscurl -X GET "https://platty.boltathread.com/api/v1/posts/bulk/{task_id}/status/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"task_id": "task_abc123",
"status": "completed",
"total": 2,
"successful": 2,
"failed": 0,
"created_posts": [
{
"id": "post_1",
"status": "scheduled"
},
{
"id": "post_2",
"status": "scheduled"
}
],
"errors": [],
"completed_at": "2025-01-28T10:31:00Z"
}Manage recurring post approvals. Recurring posts generate content that requires approval before publishing.
/api/v1/posts/recurring/{review_id}/approvecurl -X POST "https://platty.boltathread.com/api/v1/posts/recurring/{review_id}/approve/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"modifications": {
"content": "Optional: modified content if needed"
}
}'{
"success": true,
"post_id": "990e8400-e29b-41d4-a716-446655440004",
"status": "scheduled",
"scheduled_at": "2025-02-01T14:00:00Z"
}/api/v1/posts/recurring/{review_id}/rejectcurl -X POST "https://platty.boltathread.com/api/v1/posts/recurring/{review_id}/reject/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"reason": "Content needs revision - tone doesn't match brand guidelines"
}'{
"success": true,
"status": "rejected",
"reason": "Content needs revision - tone doesn't match brand guidelines"
}Manage templates for recurring content generation. Create loops (recurring templates) via API, render template content without creating posts, and manage existing templates.
/api/v1/templates/recurringcurl -X POST "https://platty.boltathread.com/api/v1/templates/recurring" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "{workspace_id}",
"name": "Monday Motivation",
"frequency": "weekly",
"schedule_day": "monday",
"schedule_time": "09:00",
"prompt": "Generate a motivational quote related to tech",
"voice_profile_id": "{voice_profile_id}"
}'{
"id": "template_123",
"status": "active",
"next_run": "2025-02-03T09:00:00Z"
}/api/v1/workspaces/{workspace_id}/loopscurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/loops/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Daily AI Tips",
"generation_time": "09:00",
"voice_profile_id": "{voice_profile_id}",
"target_account_or_bucket": "account:{account_id}",
"topics": ["ai_tools", "productivity"],
"content_size": "standard",
"context": "Focus on practical tips for developers"
}'{
"id": "template_456",
"name": "Daily AI Tips",
"generation_time": "09:00:00",
"status": "active",
"created_at": "2025-02-01T10:00:00Z"
}/api/v1/workspaces/{workspace_id}/templates/{template_id}/rendercurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/templates/{template_id}/render/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"topic_seed": "AI productivity tools for remote teams",
"context": "Focus on practical tips"
}'{
"template_id": "template_789",
"template_name": "Daily AI Tips",
"generated_content": "Here are 3 AI productivity tools every remote team should try...",
"voice_profile_used": "Company Brand Voice",
"generated_at": "2025-02-01T10:30:00Z"
}Submit posts for team review, approve or reject them, and list pending reviews. Required when Safe Mode is enabled or for team collaboration workflows.
/api/v1/workspaces/{workspace_id}/posts/submit-for-reviewcurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/submit-for-review/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"post_ids": ["post_id_1", "post_id_2"],
"note": "AI drafts ready for review"
}'{
"submitted": 2,
"failed": 0,
"results": [
{
"post_id": "post_id_1",
"status": "submitted"
},
{
"post_id": "post_id_2",
"status": "submitted"
}
]
}/api/v1/workspaces/{workspace_id}/posts/{post_id}/approvecurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/{post_id}/approve/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"schedule_mode": "approve_only",
"comments": "Looks good!"
}'{
"post_id": "post_id_1",
"status": "Approved",
"scheduled": false
}/api/v1/workspaces/{workspace_id}/reviewscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/reviews/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"reviews": [
{
"id": "review_123",
"post_id": "post_456",
"status": "pending",
"submitted_at": "2025-01-20T14:22:00Z",
"submitted_by": "agent_789"
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/recurring-reviewscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/recurring-reviews/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"reviews": [
{
"id": "rr_123",
"post_id": "post_456",
"template_id": "template_789",
"status": "pending",
"generated_at": "2025-01-20T10:00:00Z"
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/team-reviewscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/team-reviews/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"reviews": [
{
"id": "tr_123",
"post_id": "post_456",
"status": "pending",
"submitted_at": "2025-01-20T14:22:00Z",
"reviewer_id": "user_789"
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/inboxcurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/inbox/?status=pending&limit=20" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"items": [
{
"id": "tr_123",
"source": "team",
"post_id": "post_456",
"post_content": "Check out our latest update!",
"status": "pending",
"submitted_by": "agent_789",
"created_at": "2025-02-01T14:22:00Z"
},
{
"id": "rr_456",
"source": "recurring",
"post_id": "post_789",
"template_name": "Daily AI Tips",
"status": "pending",
"created_at": "2025-02-01T09:00:00Z"
}
],
"count": 2,
"has_more": false
}Export workspace activity logs for compliance, debugging, and monitoring. Combines post activity and admin audit events into a unified timeline.
/api/v1/workspaces/{workspace_id}/audit-logcurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/audit-log/?start_time=2025-01-01T00:00:00Z&end_time=2025-02-01T00:00:00Z&limit=100" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"events": [
{
"source": "post_activity",
"action": "status_change",
"actor": "agent: Content Bot",
"resource_type": "post",
"resource_id": "post_123",
"details": {
"previous_status": "Draft",
"new_status": "Scheduled"
},
"timestamp": "2025-01-28T14:30:00Z"
},
{
"source": "admin_audit",
"action": "api_key_created",
"actor": "user@example.com",
"resource_type": "api_key",
"resource_id": "key_456",
"details": {
"key_name": "Production Key"
},
"timestamp": "2025-01-28T10:00:00Z"
}
],
"count": 2,
"has_more": false
}Agents are the primary automation entity. Create and manage agents, their jobs (scheduling and triggers), job runs, and hire from preset templates.
Every endpoint in this section is governed by the agents:manage scope. There is
no separate "agent key" type — any API key that holds agents:manage can create,
configure, run, and delete agents. To drive agents from your own code (e.g. BoltaClaw /
OpenClaw, or any orchestrator), generate a regular API key with agents:manage:
posts:write,
ai:generate, voice:read), since job runs act under the calling key's scopes.403 with agents:manage named in the error message.A V2 agent is the automation entity you hire and schedule. Creating one auto-provisions a workspace principal + key behind the scenes, so you don't manage a separate credential per agent. An agent's role, key, and autonomy are managed in the Agents Hub in the dashboard — the API exposes the same controls via the PATCH endpoint below.
Every operation here is also exposed as an MCP tool on the hosted server, so
MCP-native agents (Claude Desktop, ChatGPT, BoltaClaw) can orchestrate without raw HTTP.
Point your client at https://mcp.bolta.ai/mcp with Authorization: Bearer <key> —
the same agents:manage scope applies. Each endpoint maps to a tool:
list-agents-v2 → GET …/agents-v2create-agent-v2 → POST …/agents-v2update-agent-v2 / delete-agent-v2 → PATCH / DELETE …/agents-v2/{id}list-agent-jobs-v2 / create-agent-job-v2 → …/agents-v2/{id}/jobsrun-agent-job-now-v2 → POST …/agents-v2/{id}/jobs/{job_id}/runslist-agent-job-runs-v2 → GET …/agents-v2/{id}/jobs/{job_id}/runshire-agent-preset-v2 → POST …/agents-v2/presets/{preset_id}/hireSee the MCP integration guide for client setup.
/api/v1/workspaces/{workspace_id}/agents-v2curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "The Hype Man",
"type": "content_creator",
"role": "creator",
"description": "Specializes in high-energy trend-jacking content",
"avatar": "🎯",
"safe_mode": false
}'/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}curl -X PATCH "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Name", "status": "active"}'/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}curl -X DELETE "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobscurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Max\'s Twitter",
"voice_profile_id": "voice-uuid",
"account_ids": ["account-uuid"],
"schedule": {"cron": "0 9 * * 1"},
"trigger": "scheduled",
"max_retries": 2
}'/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}curl -X PATCH "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Job Name", "status": "active"}'/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}curl -X DELETE "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/runscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/runs/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/runscurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/{agent_id}/jobs/{job_id}/runs/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'/api/v1/workspaces/{workspace_id}/agents-v2/presetscurl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/presets/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/presets/{preset_id}curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/presets/{preset_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"/api/v1/workspaces/{workspace_id}/agents-v2/presets/{preset_id}/hirecurl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/agents-v2/presets/{preset_id}/hire/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "My Hype Man", "job_name": "Twitter Job", "voice_profile_id": "voice-uuid", "account_ids": ["account-uuid"]}'Generate brand-consistent AI images. Use the image_prompt from voice/generate for best results, with optional logo reference for visual identity.
/api/v1/image/generateai:generate permission. Credits are deducted per image (1 for standard, 3 for high-end models).curl -X POST "https://platty.boltathread.com/api/v1/image/generate/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A professional headshot in a modern office setting",
"reference_image_url": "https://example.com/logo.png",
"num_images": 1,
"image_size": "square_hd",
"model": "fal-ai/nano-banana-2"
}'Get insights into your content performance and platform growth.
/api/v1/analytics/platformcurl -X GET "https://platty.boltathread.com/api/v1/analytics/platform?workspace_id={workspace_id}&range=30d" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"total_impressions": 50000,
"total_engagements": 2500,
"growth_rate": 15.5
}Outbound webhooks for event notifications.
Outbound webhooks (event callbacks like post.published / post.failed to a URL
you control) are not yet available. There is currently no POST /api/v1/webhooks
endpoint; calling it returns 404.
This page previously documented a POST /api/v1/webhooks route that was never built —
it has been removed so you don't integrate against a dead endpoint.
Need event notifications today? Poll the relevant resource (e.g. scheduled posts via
GET /api/v1/workspaces/{workspace_id}/posts/scheduled/) on an interval, or email
support@bolta.ai to register interest so we prioritize the webhook build.
Agent service accounts use role-based permissions. Each role grants a specific set of API scopes that determine which endpoints and skill planes are accessible.
| Permission | Viewer | Creator | Editor | Admin |
|---|---|---|---|---|
| posts:read | Yes | Yes | Yes | Yes |
| posts:write | — | Yes | Yes | Yes |
| posts:delete | — | — | Yes | Yes |
| accounts:read | Yes | Yes | Yes | Yes |
| accounts:connect | — | — | — | Yes |
| recurring:manage | — | Yes | Yes | Yes |
| voice:read | Yes | Yes | Yes | Yes |
| voice:write | — | Yes | Yes | Yes |
| ai:generate | — | Yes | Yes | Yes |
| content:bulk | — | — | Yes | Yes |
| workspace:read | Yes | Yes | Yes | Yes |
| review:submit | — | Yes | Yes | Yes |
| review:approve | — | — | Yes | Yes |
| audit:export | — | — | Yes | Yes |
| team:manage | — | — | — | Yes |
| team:manage_keys | — | — | Yes | Yes |
| Total scopes | 4 | 9 | 14 | 16 |
| Plane | Description | Skills | Min Role |
|---|---|---|---|
| Init | Voice bootstrap and training | 4 | Creator |
| Content | Drafting and content planning | 3 | Creator |
| Automation | Scheduled generation and publishing | 2 | Creator |
| Review | Approval workflows and triage | 3 | Viewer |
| Control | Audit, key rotation, and agent management | 4 | Viewer |
Viewer unlocks 2 planes (Review, Control read-only). Creator unlocks all 5 planes. Editor adds approval and publishing skills. Admin adds agent management skills.
API rate limits help ensure fair usage and system stability. All limits are tracked per API key.
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200{
"error": "Rate limit exceeded",
"message": "API rate limit exceeded (per_minute: 100 requests). Limit resets at 2026-01-28T06:00:00.",
"rate_limit": {
"limit": 100,
"limit_type": "per_minute",
"reset_time": "2026-01-28T06:00:00"
}
}The response also includes a Retry-After header indicating when you can retry.
If you need higher rate limits for your use case, please contact our team:
Include details about your use case, expected request volume, and API key ID (optional) for faster processing.
Social Buckets
Group social accounts into buckets for easier cross-posting.
/api/v1/bucketsnameBucket name
account_idsList of account IDs
Response Example