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), and send them to a reviewer for approval (they get an email)
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.An organization holds one or more brands; in the API a brand is a workspace, and its ID goes in the path of most calls. A key (or an OAuth connection) belongs to one organization and reaches the brands chosen for it. Organization settings, team and billing are managed in the Bolta app; a key sees the organization only as the organization field on each workspace.
/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": "Acme",
"workspace_type": "team",
"safe_mode": false,
"timezone": "America/New_York",
"member_count": 3,
"accounts_count": 4,
"user_role": "owner",
"organization": {
"id": "7c1d0000-0000-0000-0000-000000000000",
"name": "Acme Group",
"logo_url": null,
"role": "owner"
}
}
]/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}/members/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/members/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"members": [
{
"id": "<user id>",
"name": "Jane Doe",
"role": "owner",
"can_receive_approval_requests": false
},
{
"id": "<user id>",
"name": "",
"role": "creator",
"can_receive_approval_requests": true
},
{
"id": "<user id>",
"name": "Dana Client",
"role": "reviewer",
"can_receive_approval_requests": true
}
],
"count": 3
}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"
}A routine is work that repeats: Bolta runs it on its schedule, even when nobody has an app open, and its drafts wait for review. Every routine starts as a draft and does nothing until it is activated. Reads need workspace:read; anything that creates or changes a routine also needs agents:manage (403 insufficient_scope without it).
/api/v1/workspaces/{workspace_id}/routines/templates/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/templates/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"templates": [
{
"template_key": "<template_key>",
"title": "<title>",
"description": "<description>",
"outcome_category": "social_posts",
"readiness": "available",
"is_creatable": true,
"supported_platforms": [
"linkedin"
],
"supported_trigger_types": [
"manual",
"schedule"
],
"default_approval_policy": "inherit",
"available_in_workspace": true,
"unavailable_reason": null
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/routines/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"routines": [
{
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "draft",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
],
"count": 1,
"total": 1
}/api/v1/workspaces/{workspace_id}/routines/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"template_key": "",
"name": "Weekly LinkedIn tips",
"goal": "Share one practical tip every Monday",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": ""
}
]
}' {
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "draft",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "draft",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/curl -X PATCH "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"guardrails": [
"No discounts or prices"
],
"expected_updated_at": "2026-11-11T15:00:00+00:00"
}'{
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "draft",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
},
"changed_fields": [
"guardrails"
]
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/activate/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/activate/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "active",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/pause/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/pause/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"reason": "user_requested"
}'{
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "paused",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/resume/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/resume/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "active",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/archive/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/archive/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "archived",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/run-now/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/run-now/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"run": {
"id": "7d0e0000-0000-0000-0000-000000000000",
"routine_id": "3f1c0000-0000-0000-0000-000000000000",
"status": "running",
"trigger": "manual",
"started_at": "2026-11-11T15:05:00+00:00",
"completed_at": null,
"artifacts": {
"created": 0,
"awaiting_you": 0,
"scheduled": 0,
"published": 0,
"failed": 0
},
"error_code": null,
"error_summary": null
},
"started": true
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/runs/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/runs/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"runs": [
{
"id": "7d0e0000-0000-0000-0000-000000000000",
"routine_id": "3f1c0000-0000-0000-0000-000000000000",
"status": "running",
"trigger": "manual",
"started_at": "2026-11-11T15:05:00+00:00",
"completed_at": null,
"artifacts": {
"created": 0,
"awaiting_you": 0,
"scheduled": 0,
"published": 0,
"failed": 0
},
"error_code": null,
"error_summary": null
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/routines/recommendations/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/recommendations/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"recommendations": [
{
"id": "c41a0000-0000-0000-0000-000000000000",
"routine_id": "3f1c0000-0000-0000-0000-000000000000",
"title": "Post on Tuesdays instead",
"reason": "Tuesday posts got approved without edits more often.",
"proposed_change": {
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "tuesday"
}
},
"reversible": true,
"status": "proposed",
"created_at": "2026-11-10T12:00:00+00:00",
"routine_name": "Weekly LinkedIn tips"
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/routines/{routine_id}/recommendations/{recommendation_id}/{action}/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/routines/{routine_id}/recommendations/{recommendation_id}/{action}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"recommendation": {
"id": "c41a0000-0000-0000-0000-000000000000",
"routine_id": "3f1c0000-0000-0000-0000-000000000000",
"title": "Post on Tuesdays instead",
"reason": "Tuesday posts got approved without edits more often.",
"proposed_change": {
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "tuesday"
}
},
"reversible": true,
"status": "applied",
"created_at": "2026-11-10T12:00:00+00:00",
"routine_name": "Weekly LinkedIn tips"
},
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "draft",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
}
}Ask Bolta to plan a routine or a campaign from a sentence. Planning saves nothing but the proposal (valid 7 days) and needs only workspace:read. Confirming it creates the routine or campaign and needs agents:manage.
/api/v1/workspaces/{workspace_id}/plan-proposals/routine/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/plan-proposals/routine/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"ask": "Two LinkedIn posts a week about hiring"
}'{
"proposal_id": "5b7e0000-0000-0000-0000-000000000000",
"kind": "routine",
"status": "proposed",
"revision": 1,
"payload": {
"name": "Monday LinkedIn tips",
"template_key": "<template_key>",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
]
},
"display": {
"title": "Monday LinkedIn tips",
"summary": "<summary>",
"cadence": "weekly",
"first_run_at": "2026-11-16T09:00:00-05:00",
"timezone": "America/New_York"
},
"preview_topics": [
"<topic>"
],
"why": null,
"rank": null,
"expires_at": "2026-11-18T15:00:00+00:00"
}/api/v1/workspaces/{workspace_id}/plan-proposals/campaign/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/plan-proposals/campaign/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"ask": "Our launch on March 3"
}'{
"proposal_id": "5b7e0000-0000-0000-0000-000000000000",
"kind": "campaign",
"status": "proposed",
"revision": 1,
"payload": {
"name": "Monday LinkedIn tips",
"template_key": "<template_key>",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
]
},
"display": {
"title": "Monday LinkedIn tips",
"summary": "<summary>",
"cadence": "weekly",
"first_run_at": "2026-11-16T09:00:00-05:00",
"timezone": "America/New_York"
},
"preview_topics": [
"<topic>"
],
"why": null,
"rank": null,
"expires_at": "2026-11-18T15:00:00+00:00"
}/api/v1/workspaces/{workspace_id}/plan-proposals/recommend-routines/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/plan-proposals/recommend-routines/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"goals": "Stay consistent on LinkedIn",
"count": 3
}'{
"status": "proposed",
"batch_id": "e19f0000-0000-0000-0000-000000000000",
"plans": [
{
"proposal_id": "5b7e0000-0000-0000-0000-000000000000",
"kind": "routine",
"status": "proposed",
"revision": 1,
"payload": {
"name": "Monday LinkedIn tips",
"template_key": "<template_key>",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
]
},
"display": {
"title": "Monday LinkedIn tips",
"summary": "<summary>",
"cadence": "weekly",
"first_run_at": "2026-11-16T09:00:00-05:00",
"timezone": "America/New_York"
},
"preview_topics": [
"<topic>"
],
"why": "<one-line fit>",
"rank": 1,
"expires_at": "2026-11-18T15:00:00+00:00"
}
],
"skipped": [
{
"name": "<name>",
"reason": "needs published posts with engagement to reuse"
}
],
"why": null
}/api/v1/workspaces/{workspace_id}/plan-proposals/{proposal_id}/revise/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/plan-proposals/{proposal_id}/revise/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"change": "Make it Tuesdays"
}'{
"proposal_id": "5b7e0000-0000-0000-0000-000000000000",
"kind": "routine",
"status": "proposed",
"revision": 2,
"payload": {
"name": "Monday LinkedIn tips",
"template_key": "<template_key>",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
]
},
"display": {
"title": "Monday LinkedIn tips",
"summary": "<summary>",
"cadence": "weekly",
"first_run_at": "2026-11-16T09:00:00-05:00",
"timezone": "America/New_York"
},
"preview_topics": [
"<topic>"
],
"why": null,
"rank": null,
"expires_at": "2026-11-18T15:00:00+00:00",
"supersedes": "5b7e0000-0000-0000-0000-000000000000"
}/api/v1/workspaces/{workspace_id}/plan-proposals/{proposal_id}/confirm/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/plan-proposals/{proposal_id}/confirm/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"switch_on": false
}'{
"proposal_id": "5b7e0000-0000-0000-0000-000000000000",
"kind": "routine",
"created": true,
"routine": {
"id": "3f1c0000-0000-0000-0000-000000000000",
"workspace_id": "{workspace_id}",
"name": "Weekly LinkedIn tips",
"status": "draft",
"template_key": "<template_key>",
"goal": "Share one practical tip every Monday",
"outcome_category": "social_posts",
"trigger_type": "schedule",
"schedule": {
"interval": "weekly",
"time": "09:00",
"day": "monday"
},
"timezone": "America/New_York",
"source_bindings": [
{
"provider": "social_account",
"ref": "<account id>"
}
],
"approval_policy": "inherit",
"last_run": null,
"next_run_at": null,
"attention_count": 0,
"display_state": "draft",
"pause_reason": null,
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:00:00+00:00"
},
"campaign": null,
"run": null,
"generation": null,
"start_error": null,
"switch_on": false
}A content campaign is one to four weeks of posts about one thing: a launch, an event, a season. Set its accounts, length, notes, sources and voice, then activate it and Bolta writes the posts for review. Not the same as the legacy calendar labels under /api/v1/campaigns. Reads need workspace:read; writes also need agents:manage.
/api/v1/workspaces/{workspace_id}/content-campaigns/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"campaigns": [
{
"id": "6f1c2a9e-0000-0000-0000-000000000000",
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release and what it unblocks",
"audience": "Ops leads at mid-size agencies",
"cta_text": "Start a free trial",
"cta_url": "https://example.com/trial",
"starts_on": "2026-11-16",
"ends_on": "2026-11-29",
"duration_weeks": 2,
"content_plan": [
{
"type": "still_image",
"count": 3,
"account_ids": [],
"days": [
"tue",
"thu"
]
}
],
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
],
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"voice_profile_id": null,
"status": "draft",
"is_runnable": false,
"next_generation_at": null,
"posts_count": 0,
"posts_planned": 3,
"allowed_transitions": [
"scheduled",
"active",
"archived"
],
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:02:11+00:00"
}
],
"count": 1,
"total": 1
}/api/v1/workspaces/{workspace_id}/content-campaigns/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release",
"starts_on": "2026-11-16",
"duration_weeks": 2
}'{
"campaign": {
"id": "6f1c2a9e-0000-0000-0000-000000000000",
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release and what it unblocks",
"audience": "Ops leads at mid-size agencies",
"cta_text": "Start a free trial",
"cta_url": "https://example.com/trial",
"starts_on": "2026-11-16",
"ends_on": "2026-11-29",
"duration_weeks": 2,
"content_plan": [
{
"type": "still_image",
"count": 3,
"account_ids": [],
"days": [
"tue",
"thu"
]
}
],
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
],
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"voice_profile_id": null,
"status": "draft",
"is_runnable": false,
"next_generation_at": null,
"posts_count": 0,
"posts_planned": 3,
"allowed_transitions": [
"scheduled",
"active",
"archived"
],
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:02:11+00:00"
}
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"campaign": {
"id": "6f1c2a9e-0000-0000-0000-000000000000",
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release and what it unblocks",
"audience": "Ops leads at mid-size agencies",
"cta_text": "Start a free trial",
"cta_url": "https://example.com/trial",
"starts_on": "2026-11-16",
"ends_on": "2026-11-29",
"duration_weeks": 2,
"content_plan": [
{
"type": "still_image",
"count": 3,
"account_ids": [],
"days": [
"tue",
"thu"
]
}
],
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
],
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"voice_profile_id": null,
"status": "draft",
"is_runnable": false,
"next_generation_at": null,
"posts_count": 0,
"posts_planned": 3,
"allowed_transitions": [
"scheduled",
"active",
"archived"
],
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:02:11+00:00"
}
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/curl -X PATCH "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"duration_weeks": 2,
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch"
}
]
}'{
"campaign": {
"id": "6f1c2a9e-0000-0000-0000-000000000000",
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release and what it unblocks",
"audience": "Ops leads at mid-size agencies",
"cta_text": "Start a free trial",
"cta_url": "https://example.com/trial",
"starts_on": "2026-11-16",
"ends_on": "2026-11-29",
"duration_weeks": 2,
"content_plan": [
{
"type": "still_image",
"count": 3,
"account_ids": [],
"days": [
"tue",
"thu"
]
}
],
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
],
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"voice_profile_id": null,
"status": "draft",
"is_runnable": false,
"next_generation_at": null,
"posts_count": 0,
"posts_planned": 3,
"allowed_transitions": [
"scheduled",
"active",
"archived"
],
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:02:11+00:00"
},
"changed_fields": [
"account_ids",
"context_notes",
"context_sources"
]
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/context-sources/analyze/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/context-sources/analyze/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"kind": "url",
"ref": "https://example.com/launch"
}'{
"campaign": {
"id": "6f1c2a9e-0000-0000-0000-000000000000",
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release and what it unblocks",
"audience": "Ops leads at mid-size agencies",
"cta_text": "Start a free trial",
"cta_url": "https://example.com/trial",
"starts_on": "2026-11-16",
"ends_on": "2026-11-29",
"duration_weeks": 2,
"content_plan": [
{
"type": "still_image",
"count": 3,
"account_ids": [],
"days": [
"tue",
"thu"
]
}
],
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
],
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"voice_profile_id": null,
"status": "draft",
"is_runnable": false,
"next_generation_at": null,
"posts_count": 0,
"posts_planned": 3,
"allowed_transitions": [
"scheduled",
"active",
"archived"
],
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:02:11+00:00"
},
"source": {
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/activate/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/activate/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"campaign": {
"id": "6f1c2a9e-0000-0000-0000-000000000000",
"name": "Spring launch",
"strategy_key": "offer_promotion",
"theme": "The 2.0 release and what it unblocks",
"audience": "Ops leads at mid-size agencies",
"cta_text": "Start a free trial",
"cta_url": "https://example.com/trial",
"starts_on": "2026-11-16",
"ends_on": "2026-11-29",
"duration_weeks": 2,
"content_plan": [
{
"type": "still_image",
"count": 3,
"account_ids": [],
"days": [
"tue",
"thu"
]
}
],
"context_notes": "Launch price is $49/mo until Dec 1.",
"context_sources": [
{
"kind": "url",
"ref": "https://example.com/launch",
"title": "Launch post",
"status": "ready"
}
],
"account_ids": [
"0b6a7c2d-0000-0000-0000-000000000000"
],
"voice_profile_id": null,
"status": "active",
"is_runnable": false,
"next_generation_at": null,
"posts_count": 0,
"posts_planned": 3,
"allowed_transitions": [
"scheduled",
"active",
"archived"
],
"created_at": "2026-11-11T15:00:00+00:00",
"updated_at": "2026-11-11T15:02:11+00:00"
}
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/posts/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/posts/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"posts": [
{
"post_id": "9c8b7a6d-0000-0000-0000-000000000000",
"source": "generated",
"status": "Draft",
"content_type": "still_image",
"content_preview": "2.0 is out. Here is what it unblocks...",
"platforms": [
"linkedin"
],
"has_pending_review": true,
"scheduled_at": "2026-11-18T14:00:00+00:00",
"published_at": null
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/posts/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/posts/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"post_ids": [
"9c8b7a6d-0000-0000-0000-000000000000"
]
}'{
"attached": [
"9c8b7a6d-0000-0000-0000-000000000000"
],
"already_present": [],
"not_found": [],
"posts_count": 1
}/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/prompts/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/content-campaigns/{campaign_id}/prompts/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"prompts": [
{
"id": "<prompt id>",
"week_start": "2026-11-16",
"content_type": "still_image",
"topic": "What 2.0 unblocks",
"account_ids": [],
"scheduled_for": null,
"status": "planned"
}
],
"open_weeks": [
"2026-11-16"
],
"next_generation": null
}Legacy: the /api/v1/campaigns routes manage calendar labels, a name and date range you tag posts with to group them on the calendar. They do not write posts. For one to four weeks of posts about one thing, use Content Campaigns.
/api/v1/campaigns/curl -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}",
"title": "Spring launch",
"start_date": "2026-03-01T00:00:00Z",
"end_date": "2026-03-31T23:59:59Z",
"color": "#3b82f6"
}'{
"campaign": {
"id": "6f1c2a7e-0000-0000-0000-000000000000",
"title": "Spring launch",
"campaign_type": "promotional",
"status": "draft",
"priority": "medium",
"start_date": "2026-03-01T00:00:00Z",
"end_date": "2026-03-31T23:59:59Z",
"color": "#3b82f6",
"icon": "megaphone",
"tags": [],
"post_count": 0,
"workspace_id": "{workspace_id}"
},
"message": "Campaign created successfully"
}/api/v1/workspaces/{workspace_id}/campaigns/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/campaigns/?status=active" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"campaigns": [
{
"id": "6f1c2a7e-0000-0000-0000-000000000000",
"title": "Spring launch",
"status": "active",
"post_count": 4
}
],
"total": 1,
"workspace_id": "{workspace_id}"
}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.
platform_specific on the postSend it with POST /api/v1/posts/ or PATCH /api/v1/posts/{post_id} (scope posts:write). It is read when the post is published.
{ "platform_specific": { "linkedin": { "visibility": "PUBLIC", "text": "LinkedIn-only wording" }, "x": { "reply_settings": "followers", "accounts": { "acme_support": { "text": "Shorter text for this one account" } } }, "youtube": { "video_title": "Launch walkthrough", "privacy_status": "unlisted" } } }
x, threads, linkedin, facebook, instagram, bluesky, mastodon, reddit, discord, tiktok, youtube, pinterest.text replaces the post text for that network.accounts holds per-account overrides. The key is matched against the account's ID, then its username or handle, then its platform ID (exact first, then case-insensitive). Pinterest matches username or ID only.platform_specific object, so send all of it. It is not validated: unknown keys are stored and ignored. It comes back inside the post's metadata, not as its own field.reply_settings (everyone, mentioned_users, followers); Threads reply_control (everyone, mentioned, followers), topic_tag; LinkedIn visibility (PUBLIC, CONNECTIONS); TikTok privacy_level, disable_comments, disable_duet, disable_stitch; YouTube video_title, video_description, tags, category_id, privacy_status (public, private, unlisted); Pinterest board_id, title, description, link; Instagram content_type, location_id, cover_url.The endpoints below (/api/v1/posts/{post_id}/details/{platform}/) hold one row of named fields per network, validated: a value outside a field's allowed set returns 400. GET needs posts:read, writes need posts:write. Over MCP, save-post sets the same fields through its platform_details argument.
/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! 💪",
"account_ids": ["880e8400-e29b-41d4-a716-446655440003"],
"requested_action": "schedule",
"scheduled_time": "2025-02-03T09:00:00"
},
{
"content": "Tip Tuesday: Always plan your content ahead! 📅",
"account_ids": ["880e8400-e29b-41d4-a716-446655440003"],
"requested_action": "schedule",
"scheduled_time": "2025-02-04T09:00:00"
}
]
}'{
"task_id": "task_abc123",
"status": "queued",
"posts_count": 2,
"scheduled_posts": 2,
"rejected": [],
"rejected_count": 0,
"message": "Bulk create posts task queued successfully"
}/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"
}'
# Send to named people for approval (emails them)
curl -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"],
"reviewer_ids": ["user_id_1"],
"title": "May launch posts",
"note": "Two posts for next week"
}'{
"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}/posts/{post_id}/reject/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/posts/{post_id}/reject/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"reason": "Too salesy for LinkedIn"
}'{
"post_id": "<post id>",
"review_id": "<review id>",
"status": "rejected",
"already_decided": false,
"categories": []
}/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
}Everything waiting for a decision in one list: drafts from routines, campaigns and people (source team), recurring posts (recurring), outreach replies drafted for conversations Bolta found (hunter) and reports (report). Replying to conversations needs a plan that includes it; otherwise 402 hunter_plan_required.
/api/v1/workspaces/{workspace_id}/inbox/curl -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": "<review id>",
"post_id": "<post id>",
"workspace_id": "{workspace_id}",
"status": "pending",
"source": "team",
"content_preview": "Three things we learned shipping 2.0...",
"content_fingerprint": "<sha>",
"workflow_run_id": "<run id>",
"scheduled_time": null,
"created_at": "2026-11-11T09:00:00Z"
},
{
"id": "<reply id>",
"reply_id": "<reply id>",
"type": "acquisition_reply",
"source": "hunter",
"status": "pending",
"content": "Good question. We ran into the same thing...",
"platform": "reddit",
"platform_url": "https://reddit.com/...",
"campaign_id": "<campaign id>",
"created_at": "2026-11-11T08:00:00Z"
}
],
"has_more": false,
"workspace_id": "{workspace_id}",
"total_team": 1,
"total_recurring": 0,
"total_hunter": 1,
"total_report": 0
}/api/v1/workspaces/{workspace_id}/approvals/waiting/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/approvals/waiting/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"total_pending": 5,
"counts": {
"posts": 4,
"articles": 1,
"team": 3,
"recurring": 2,
"outreach_replies": 2,
"comment_replies": 0
},
"expiring": {
"today": 0,
"within_3_days": 1
},
"waiting_total": 7,
"workspace_id": "{workspace_id}"
}/api/v1/workspaces/{workspace_id}/inbox/hunter/{reply_id}/curl -X PATCH "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/inbox/hunter/{reply_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"content": "Good question. Here is what worked for us..."
}'{
"reply_id": "<reply id>",
"status": "pending",
"message": "Reply draft updated.",
"reply": {
"reply_id": "<reply id>",
"status": "pending",
"content": "Good question. Here is what worked for us...",
"platform": "reddit",
"sent_at": null
}
}/api/v1/workspaces/{workspace_id}/inbox/hunter/{reply_id}/send/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/inbox/hunter/{reply_id}/send/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'{
"reply_id": "<reply id>",
"status": "queued",
"message": "Reply approved and queued for sending.",
"reply": {
"reply_id": "<reply id>",
"status": "pending",
"platform": "reddit",
"sent_at": null
}
}/api/v1/workspaces/{workspace_id}/inbox/hunter/{reply_id}/action/curl -X POST "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/inbox/hunter/{reply_id}/action/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"action": "reject"
}'{
"reply_id": "<reply id>",
"status": "rejected",
"message": "Reply rejected and removed from queue."
}/api/v1/workspaces/{workspace_id}/engagement/replies/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/engagement/replies/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"engagements": [
{
"engagement_id": "<id>",
"platform": "reddit",
"target_id": "abc123",
"target_type": "post",
"content": "...",
"status": "pending",
"needs_approval": true,
"reviewer_approved": null,
"canonical_url": "",
"created_at": "2026-11-11T08:00:00Z",
"sent_at": null
}
],
"count": 1
}/api/v1/workspaces/{workspace_id}/engagement/replies/{engagement_id}/curl -X GET "https://platty.boltathread.com/api/v1/workspaces/{workspace_id}/engagement/replies/{engagement_id}/" \
-H "Authorization: Bearer bolta_sk_your_api_key_here"{
"engagement_id": "<id>",
"platform": "reddit",
"status": "sent",
"platform_reply_id": "<id>",
"canonical_url": "https://reddit.com/...",
"error": ""
}A brand can require a client to sign off before anything is published. Sign-off requests, client reviewers and the approval policy are managed in the Bolta app and are not available to API keys. What a key does see:
client_signoff on each post. GET /api/v1/posts/{post_id} (and a successful schedule) returns
client_signoff: {"required": false, "state": "not_required"}, {"required": true, "state": "signed_off", "signed_off_at": "..."},
or {"required": true, "state": "waiting_on_client" | "not_sent", "reason": "..."}.409 with CLIENT_SIGNOFF_REQUIRED; scheduling it is refused the same way or sent back to review (status Pending Approval).
Approving while a client review is open returns 409 client_review_pending./policy/ carry no sign-off fields; read the post./organizations/ routes (org settings, team, brand people) are for signed-in users only.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.
These endpoints are REST only. The MCP server has no agent tools: AI apps set up work
that repeats as routines instead (plan, confirm-plan, activate-routine).
See the MCP guide for the tool list.
/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: 1793548860
RateLimit: "default";r=95;t=60
RateLimit-Policy: "default";q=100;w=60
RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 60{
"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 (seconds) and the X-RateLimit-* headers for the limit that was hit. Limits are counted per API key in fixed minute, hour and day windows; requests from a signed-in browser session are not counted.
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