developer API v1

query parameters

response

{
  "data": [
    {
      "id": "uuid",
      "name": "string",
      "status": "draft|manual|trigger|scheduled|running|completed|partial|failed|cancelled",
      "platforms": ["twitter", "reddit"],
      "scheduled_date": "ISO 8601 | null",
      "product_url": "string | null",
      "product_description": "string | null",
      "persona_id": "uuid | null",
      "media_mode": "images | video | null",
      "media_assets": [
        { "type": "image", "url": "https://...", "fal_request_id": "..." }
      ] | null,
      "dropspace_platforms": ["twitter"] | null,
      "user_platform_accounts": {
        "twitter": "token-uuid",
        "linkedin:personal": "token-uuid",
        "facebook:page:123456": "token-uuid"
      } | null,
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 42, "total_pages": 1 }
}

request body

response

// 201 (create only): the full launch object is echoed back
{
  "data": {
    "id": "uuid",
    "name": "announcing our new feature",
    "status": "trigger",
    "platforms": ["linkedin", "twitter", "reddit"],
    "scheduled_date": null,
    "product_url": "https://example.com",
    "product_description": "a tool that does X",
    "persona_id": null,
    "media_mode": "images",
    "dropspace_platforms": ["twitter"],
    "user_platform_accounts": { "linkedin": "uuid", "reddit": "uuid" },
    "platform_contents": {
      "twitter": { "content": "..." },
      "linkedin": { "content": "..." },
      "reddit": { "content": "...", "title": "..." }
    },
    "media_assets": [
      { "id": "uuid", "url": "https://...", "type": "image", "filename": "photo.jpg", "size": 12345, "mime_type": "image/jpeg" }
    ],
    "error_message": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-03-25T12:00:00Z",
    "updated_at": "2026-03-25T12:00:00Z"
  }
}

// 200 (publish: true, wait: true): adds posting_status with per-platform results
{
  "data": {
    "id": "uuid",
    "name": "announcing our new feature",
    "status": "completed",
    "platforms": ["linkedin", "twitter"],
    "scheduled_date": null,
    "product_url": "https://example.com",
    "product_description": "a tool that does X",
    "persona_id": null,
    "media_mode": null,
    "dropspace_platforms": null,
    "user_platform_accounts": { "linkedin": "uuid", "twitter": "uuid" },
    "platform_contents": { "twitter": { "content": "..." }, "linkedin": { "content": "..." } },
    "media_assets": null,
    "error_message": null,
    "started_at": "2026-03-25T12:00:05Z",
    "completed_at": "2026-03-25T12:00:30Z",
    "created_at": "2026-03-25T12:00:00Z",
    "updated_at": "2026-03-25T12:00:30Z",
    "posting_status": {
      "twitter": { "status": "success", "post_url": "https://x.com/user/status/123" },
      "linkedin": { "status": "success", "post_url": "https://linkedin.com/feed/update/..." }
    }
  }
}

errors

notes

• the media field lets you upload images/videos inline via URL or base64 without pre-uploading to storage - the server handles upload and returns media_assets in the response
• media and media_assets are mutually exclusive - use media for inline upload, or media_assets if you've already uploaded files to storage
• **operational tip**: the inline `media` URL fetch runs inside the POST request (bound by the 5-min route maxDuration) and streams the body through to storage. for videos >~50 MB or slow source hosts, pre-uploading to your own storage and passing `media_assets` is more reliable: it lets the publish worker pull from a fast intra-region URL when it actually posts to the platform, instead of bottlenecking the create request
• content is generated automatically via Claude using your description, scraped website data, and persona style
• custom_content and platform_contents are mutually exclusive - use one or the other (or neither for full AI generation)
• product_url is optional but enhances AI generation by providing scraped website data for additional context
• if platform_contents is provided, those platforms skip AI generation - only platforms without a truthy content field are generated
• custom_content as a string distributes the same text to all platforms - validated against the lowest character limit. as an array (string[]), it creates a numbered twitter thread and joins tweets with double newlines for other platforms. array form requires twitter in platforms
• partial coverage is supported: provide content for some platforms and let AI generate the rest
• for Twitter threads, use `platform_contents.twitter.thread: ["tweet 1", "tweet 2"]` instead of `content` - each tweet ≤ 280 chars (≤ 25,000 for X Premium accounts), max 6 tweets. mutually exclusive with `content`
• for Reddit, `platform_contents.reddit.metadata.subreddits` (string[], max 10) posts the launch once per subreddit: each destination gets its own posting log, and posts are paced automatically to respect Reddit's shared rate limit. omit it to post to the default community. read the per-destination outcome from `GET /launches/:id/destinations` (it names the `subreddit` on each row - `GET /launches/:id/status` reports them all as the same `platform`), and retry one community with `POST /launches/:id/retry` + `{ "subreddit": "<name>" }`. **each subreddit has its own rules**: many restrict or ban promotional posts, some require flair, and posting where the account has no history gets filtered by AutoMod or the spam filter. prefer a few genuinely relevant subreddits over a broad blast; the web app surfaces per-community rules and account standing before posting
• for Reddit multi-account, each connected reddit account can target its OWN subreddits: set `platform_contents["reddit:<account_id>"].metadata.subreddits` for a specific account (falls back to the base `reddit` block). a subreddit is posted by at most ONE of your connected reddit accounts per launch - if two accounts list the same community, the first (primary first) posts it and the other is skipped with `SUBREDDIT_ALREADY_TARGETED`
• for Reddit, `platform_contents.reddit.metadata.first_comment` (string, max 1,500 chars) posts a comment under each Reddit post once it is confirmed live - useful for the link or extra context when the post itself should stay native. a first-comment failure never affects the launch result
• media is distributed to selected platforms with per-platform limits (Instagram/Facebook: 10, Reddit: 20, TikTok: 35)
• Instagram requires at least one image, video, or AI-generated video. TikTok requires video or photos
• TikTok direct posts (`tiktok_settings.publish_mode: "direct"`, the default) require `tiktok_settings.privacy_level` to be set before publishing (TikTok Content Sharing Guidelines). set it at creation time via `platform_contents.tiktok.tiktok_settings` or update it later via PATCH. branded content (`is_branded_content: true`) cannot use SELF_ONLY privacy. with `publish_mode: "draft"` the post is uploaded to the creator's TikTok inbox to finish and publish in the TikTok app, so `privacy_level` is not required
• when `publish: true`, the launch is created and immediately queued for publishing - returns **202** instead of 201. if publish validation fails after creation, returns 201 with a `publish_error` field containing `{ code, message }` - retry via `POST /launches/:id/publish`
• `publish` and `scheduled_date` are mutually exclusive - use one or the other
• `publish: true` requires at least one posting account (`user_platform_accounts` or `dropspace_platforms`). with API key auth, both `write` and `send` scopes are required
• `wait: true` runs the publisher synchronously and returns 200 with `posting_status` containing per-platform results and post URLs. the request stays open until all platforms finish (typically 10-30s, up to 60s+ with Instagram/TikTok). if any platform fails, `posting_status` still shows successes - check `status` field per platform

response

{
  "data": {
    "id": "uuid",
    "name": "string",
    "status": "completed",
    "platforms": ["linkedin", "twitter"],
    "platform_contents": { "twitter": { "content": "..." } },
    "media_assets": [],
    "dropspace_platforms": ["twitter"] | null,
    "user_platform_accounts": {
      "twitter": "token-uuid",
      "linkedin:personal": "token-uuid"
    } | null,
    "posting_status": {
      "twitter": { "status": "success", "post_url": "https://x.com/...", "posted_at": "ISO 8601" },
      "linkedin": { "status": "failed", "error_message": "rate limited by platform" }
    },
    "started_at": "ISO 8601",
    "completed_at": "ISO 8601"
  }
}

errors

request body

errors

notes

• all fields are optional but at least one must be provided
• a running launch can only be updated to set status to cancelled
• unrecognized fields return a 400 error
• status is auto-derived for editable launches (draft, manual, trigger, scheduled). the server determines status based on your launch configuration: has posting accounts (user_platform_accounts or dropspace_platforms) + scheduled_date → scheduled. has posting accounts + no scheduled_date → trigger. has content + no posting accounts → manual. you cannot force "manual" on a launch with posting accounts. it will auto-transition to "trigger". to unschedule a launch, PATCH with { "scheduled_date": null }, status auto-becomes "trigger"
• platform_contents merges per platform - existing platforms not included in the update are preserved. within a platform, fields you include replace the old value
• for Twitter threads, use `platform_contents.twitter.thread: ["tweet 1", "tweet 2"]` instead of `content` - each tweet ≤ 280 chars (≤ 25,000 for X Premium), max 6 tweets
• media and media_assets replace existing media entirely (no merging)
• TikTok `tiktok_settings` is deep-merged - you can update individual fields (e.g. only `privacy_level`) without overwriting the rest

errors

response

{ "data": { "message": "publish queued" } }

errors

notes

• the launch transitions to running - poll /status or listen for launch.completed / launch.failed / post.deleted webhooks
• when validation fails (LAUNCH_007), the response includes a `details` array listing all issues that must be fixed before publishing
• platform validation checks: character limits (all platforms), Reddit title ≤ 300 chars, Reddit video mode needs video (thumbnail auto-generated if not provided), Reddit image mode needs images, Instagram reel needs video, Instagram carousel needs ≥ 2 images, Instagram post_type "carousel" needs 2 to 10 images and videos combined, TikTok requires privacy_level in tiktok_settings (unless publish_mode is "draft"), TikTok video mode needs video, TikTok photo mode needs images, YouTube requires video, YouTube title ≤ 100 chars, YouTube description ≤ 5,000 chars
• **video size**: per-platform limit is 512 MB. YouTube uploads stream chunked through the worker (memory-bounded). multi-platform launches that share the same video pre-download it once; for very large files (>~300 MB) prefer publishing to one platform at a time, since the pre-download buffer doubles peak memory until each poster releases its handle

response

{
  "data": {
    "message": "retry queued",
    "platforms": ["reddit", "tiktok"]
  }
}

errors

request body

response

{
  "data": {
    "retried": ["twitter", "reddit"],
    "succeeded": ["twitter"],
    "still_failing": ["reddit"],
    "rate_limited": []
  }
}

errors

request body

response

{
  "data": {
    "id": "uuid",
    "name": "announcing our new feature",
    "platform_contents": {
      "twitter": { "content": "1/ Fresh new thread..." },
      "linkedin": { "content": "New version..." }
    }
  },
  "generation": {
    "platforms_generated": ["linkedin", "twitter"],
    "failures": null
  }
}

errors

notes

• existing content for other platforms is preserved
• media, video sources, and generated videos are never overwritten

response

{
  "data": {
    "launch_id": "uuid",
    "launch_status": "completed",
    "posting_logs": [
      {
        "id": "uuid",
        "platform": "twitter",
        "status": "success",
        "post_url": "https://x.com/...",
        "post_id": "string | null",
        "error_message": "string | null",
        "error_code": "string | null",
        "attempt_count": 1,
        "posted_at": "ISO 8601",
        "created_at": "ISO 8601"
      }
    ]
  }
}

errors

notes

• launch_status is "completed" when every destination posted, "partial" when some posted and some failed, and "failed" when none posted.
• a platform in the launch's platforms that has no account to post from (no user_platform_accounts key for it and no dropspace official posting) gets a failed log with error_code "NO_ACCOUNT" instead of being skipped, so a launch that posted elsewhere reads "partial". when none of the platforms has an account, nothing is posted, no logs are written, and the launch is marked "completed" as ready for manual posting.
• error_code is a stable machine-readable code for a failed log. see posting error codes in the error handling docs for the full list and what to do about each one.

response

{
  "data": [
    {
      "posting_log_id": "uuid",
      "platform": "reddit",
      "account_type": "user:subreddit:webdev",
      "subreddit": "webdev",
      "status": "success",
      "post_url": "https://reddit.com/r/webdev/comments/...",
      "post_id": "string | null",
      "error_message": "string | null",
      "error_code": "string | null",
      "attempt_count": 1,
      "posted_at": "ISO 8601",
      "created_at": "ISO 8601"
    },
    {
      "posting_log_id": "uuid",
      "platform": "reddit",
      "account_type": "user:subreddit:SideProject",
      "subreddit": "SideProject",
      "status": "failed",
      "post_url": null,
      "post_id": null,
      "error_message": "post removed by automod",
      "error_code": "POST_REMOVED",
      "attempt_count": 1,
      "posted_at": null,
      "created_at": "ISO 8601"
    }
  ]
}

errors

response

{
  "data": {
    "launch_id": "uuid",
    "launch_name": "announcing our new feature",
    "launch_status": "completed",
    "summary": { "total": 3, "successful": 3, "failed": 0, "pending": 0 },
    "fetched_at": "2026-02-22T10:00:00Z",
    "next_refresh_at": "2026-02-22T10:05:00Z",
    "platforms": [
      {
        "platform": "twitter",
        "status": "success",
        "post_url": "https://x.com/...",
        "post_id": "1234567890",
        "posted_at": "ISO 8601",
        "cache_status": "refreshed",
        "is_deleted": false,
        "deleted_detected_at": null,
        "deletion_reason": null,
        "metrics": {
          "likes": 42,
          "retweets": 12,
          "replies": 5,
          "quotes": 2,
          "bookmarks": 8,
          "impressions": 1500,
          "urlClicks": 23,
          "profileClicks": 7,
          "tracked_clicks": 19,
          "fetched_at": "2026-02-22T10:00:00Z"
        }
      },
      {
        "platform": "reddit",
        "status": "success",
        "post_url": "https://reddit.com/...",
        "post_id": "abc123",
        "posted_at": "ISO 8601",
        "cache_status": "fresh",
        "is_deleted": false,
        "deleted_detected_at": null,
        "deletion_reason": null,
        "metrics": {
          "score": 156,
          "upvotes": 200,
          "upvoteRatio": 0.78,
          "comments": 34,
          "fetched_at": "2026-02-22T09:58:00Z"
        }
      }
    ]
  }
}

errors

notes

• metrics.tracked_clicks appears when the launch was created with track_links: clicks on its tracked link for that platform, counted on the platform's first post so summing posts never double-counts.
• metrics refresh on a per-platform cycle. YouTube statistics are refreshed for you every 10 minutes in the background, so calling more often returns the same numbers from cache. other platforms are fetched live from their APIs when the cached copy is older than 5 minutes; calling this endpoint triggers that refresh automatically.
• fetched_at is the most recent timestamp when metrics were collected. next_refresh_at is the earliest time a call could return new numbers (fetched_at + 10 min for YouTube, + 5 min for other platforms) - polling before it only re-reads the cache.
• cache_status per platform: fresh (inside the refresh cycle, from cache), refreshed (fetched from platform API on this call), stale (rate limited or no token, returning older data), unavailable (no data exists). omitted for non-success posts (failed, pending).
• rate-limited platforms return stale cached data instead of failing - the response always includes the best available metrics.
• metric fields vary by platform: Twitter (likes, retweets, replies, quotes, bookmarks, impressions, urlClicks, profileClicks), LinkedIn (impressions, uniqueImpressions, likes, comments, shares, clicks, engagement), Facebook (reactions, likes, comments, shares - likes mirrors reactions.total), Instagram (views, engagement, saved, likes, comments, shares), Reddit (score, upvotes, upvoteRatio, comments), TikTok (views, likes, comments, shares)
• facebook has no impressions or reach: those come from the platform's insights endpoint, which dropspace does not request. facebook story metrics are unavailable for the same reason - story insights are wired for instagram only.
• a null metric means the platform did not disclose it, which is different from 0: youtube returns likes: null when the owner hides the like count and comments: null when comments are disabled.
• an instagram story reports views, reach, replies, and frames only while it is live: Meta serves story insights for 24 hours with no backfill. views and replies are summed across frames and reach is the widest single frame. views is null when Meta does not report it, and a story under 5 viewers returns story_insights_withheld: true instead of numbers (withheld, not zero).
• is_deleted indicates whether the post was detected as removed from the platform. when true, deleted_detected_at contains the detection timestamp and deletion_reason contains the reason. possible values: not_found (post no longer exists), gone (permanently removed, HTTP 410), creator_deleted (deleted by creator), moderation_removed (removed by moderation), account_deleted (account was deleted), spam_filtered (caught by spam filter). deletion is detected during metrics refresh.

query parameters

response

{
  "data": {
    "launch_id": "uuid",
    "posts": [
      {
        "post_id": "dQw4w9WgXcQ",
        "platform": "youtube",
        "post_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
        "posted_at": "ISO 8601",
        "status": "ok",
        "detail": null,
        "comments": [
          {
            "id": "UgxKREWxIg...",
            "text": "great launch!",
            "author_username": "somefan",
            "author_display_name": "@somefan",
            "author_profile_image_url": "https://yt3.ggpht.com/...",
            "like_count": 7,
            "reply_count": 2,
            "published_at": "ISO 8601"
          }
        ],
        "next_cursor": "QURTSl9p..."
      },
      {
        "post_id": "7301234567890",
        "platform": "tiktok",
        "post_url": "https://tiktok.com/...",
        "posted_at": "ISO 8601",
        "status": "unsupported",
        "detail": "tiktok's api does not expose comment content to third-party apps - comment counts are available in analytics",
        "comments": [],
        "next_cursor": null
      }
    ]
  }
}

errors

notes

• comments are top-level only, ordered newest first, and cached for ~60 seconds per page.
• platform support is explicit per post via status: ok (comments returned), unsupported (the platform's api does not expose comment content), comments_disabled (turned off on the post), post_deleted (post no longer exists), unavailable (transient: rate limited, quota, or account not connected - retry later). detail carries the human-readable reason for every non-ok status.
• youtube and instagram return comment content. instagram connections made before 08/25/2026 read unsupported with a reconnect prompt until the creator reconnects instagram once; tiktok exposes comment counts only (see analytics).
• to page through one post's comments, pass post_id plus the next_cursor from the previous response. next_cursor is null on the last page.

response

{
  "data": {
    "reply_id": "UgzXK..."
  }
}

errors

notes

• reply_id is the platform's id for the created reply; null when the platform doesn't return one.
• a successful reply invalidates the post's cached comment pages, so the next GET reflects it immediately.

response

{
  "data": {
    "comment_id": "17895695668004550",
    "hidden": true
  }
}

errors

notes

• comments read back with `hidden: true` from GET /launches/:id/comments once hidden.
• a successful change invalidates the post's cached comment pages, so the next GET reflects it immediately.

query parameters

response

{
  "data": {
    "comment_id": "17895695668004550",
    "deleted": true
  }
}

errors

notes

• deletion is permanent - prefer hide when the comment may need to come back.

query parameters

response

{
  "data": [
    {
      "launch_id": "uuid",
      "launch_name": "announcing our new feature",
      "launch_status": "completed",
      "summary": { "total": 3, "successful": 2, "failed": 1, "pending": 0 },
      "platforms": [
        {
          "platform": "twitter",
          "status": "success",
          "post_url": "https://x.com/...",
          "post_id": "1234567890",
          "posted_at": "ISO 8601",
          "is_deleted": false,
          "deleted_detected_at": null,
          "deletion_reason": null,
          "cache_status": "fresh",
          "metrics": {
            "likes": 42,
            "retweets": 12,
            "impressions": 1500,
            "fetched_at": "2026-02-22T10:00:00Z"
          }
        }
      ]
    }
  ],
  "errors": [
    { "id": "invalid-uuid", "error": { "code": "LAUNCH_001", "message": "launch not found" } }
  ]
}

errors

notes

• returns cached analytics only - does NOT trigger a live refresh from platform APIs. use the single-launch endpoint GET /launches/:id/analytics to trigger a fresh fetch.
• accepts up to 100 launch IDs. duplicate IDs are deduplicated. counts as 1 rate limit hit.
• response includes partial results: valid launches in data[], invalid/not-found in errors[].
• cache_status per platform: fresh (< 5 min old), stale (older cached data), unavailable (no metrics exist). never returns refreshed (no live fetch). omitted for non-success posts (failed, pending).
• metric fields vary by platform - same as single-launch analytics endpoint.

response

{
  "data": {
    "success": true,
    "platform": "twitter",
    "post_id": "1234567890",
    "deleted_at": "ISO 8601"
  }
}

errors

notes

• requires `write` scope on your API key (included in the default scope set)
• only works for Twitter, Facebook, LinkedIn, and Reddit - Instagram and TikTok do not support API deletion
• the posting log must have status 'success' and a valid post_id
• if the post was already deleted on the platform (404), it is treated as a successful deletion
• on success, the posting log status is updated to 'deleted'
• logId is the posting_log UUID from the /status endpoint

response

{
  "data": {
    "results": [
      { "success": true, "platform": "twitter", "post_id": "123", "deleted_at": "ISO 8601" },
      { "success": true, "platform": "linkedin", "post_id": "urn:li:share:456", "deleted_at": "ISO 8601" },
      { "success": false, "platform": "instagram", "post_id": "789", "error": "platform does not support deletion", "error_code": "DELETE_NOT_SUPPORTED" }
    ],
    "no_failures": false,
    "deleted_count": 2,
    "failed_count": 0,
    "skipped_count": 1
  }
}

errors

notes

• requires `write` scope on your API key (included in the default scope set)
• only deletes from Twitter, Facebook, LinkedIn, and Reddit
• Instagram and TikTok posts are skipped with DELETE_NOT_SUPPORTED (require manual deletion)
• returns detailed results per post including success/failure status
• skipped_count includes platforms that don't support API deletion

query parameters

response

{
  "data": {
    "platforms": [
      {
        "platform": "instagram",
        "entity_id": null,
        "current": { "followers": 10432, "following": 812, "media": 340, "captured_at": "2026-07-22T06:00:00Z" },
        "series": [
          { "captured_at": "2026-06-22T06:00:00Z", "followers": 9800 },
          { "captured_at": "2026-07-22T06:00:00Z", "followers": 10432 }
        ],
        "growth": {
          "window_days": 30,
          "follower_delta": 632,
          "follower_pct": 0.0645,
          "baseline_captured_at": "2026-06-22T06:00:00Z",
          "effective_window_days": 30
        }
      }
    ],
    "as_of": "2026-07-22T18:00:00Z"
  }
}

errors

notes

• covers instagram, youtube, tiktok, twitter, and facebook - the platforms whose follower counts the official apis expose. other connected platforms (linkedin, reddit) are omitted.
• facebook follower counts are reported per connected page (each page reports its own followers); twitter reports followers, following, and tweet count.
• counts are read on-demand when you call this endpoint and cached for 15 minutes. youtube is the exception, because each youtube read spends a shared daily quota: while you keep reading an account, its youtube count is refreshed in the background about once an hour, and an on-demand read re-fetches at most every 6 hours if that refresh is delayed. each fresh read records a history point - so a newly connected account appears on its first call and builds growth history from there.
• growth is computed from the earliest and latest snapshot inside the window; follower_pct is a fraction (0.0645 = 6.45%). delta and pct are null until at least one snapshot exists in the window.
• history points are recorded when you read (at most one per account per day), so the oldest point inside the window can be much younger than window_days. baseline_captured_at is when the delta is measured from, and effective_window_days is the span it actually covers - read it before comparing growth across accounts.
• youtube history points are kept for 30 days (YouTube's API storage limit), so youtube growth reaches back about 30 days even when window_days is larger; effective_window_days says how far it actually reaches. other platforms keep their full history.
• current.captured_at is when the returned count was actually read from the platform, never when it was served: a cached or background-refreshed count keeps its original read time, a youtube count returned while youtube's daily quota is exhausted carries the time of the last successful read, and if the platform call fails with nothing cached it is when the newest stored point was captured.
• data collection uses each platform's official read api, not scraping - so it only covers accounts the creator has connected.

request body

response

{
  "data": {
    "icp_summary": "indie developers shipping side projects",
    "suggestions": [
      {
        "name": "SideProject",
        "title": "Side Project",
        "subscribers": 180000,
        "over18": false,
        "subreddit_type": "public",
        "promo_policy": "allowed",
        "promo_evidence": "self-promotion saturday thread",
        "standing": {
          "level": "green",
          "tier": "active",
          "promo_posts_here": 1,
          "contributions_here": 14,
          "promo_share": 0.06,
          "reasons": ["you're active here (14 comments)"]
        },
        "reason": "indie devs share and get feedback on side projects here"
      }
    ]
  }
}

errors

notes

• api-key auth only: needs the caller's reddit oauth token to verify subs + compute standing. wallet/mpp agents get an empty result.
• nothing here posts; it only reads. rate-limited per account (the discovery sweep is expensive on reddit's shared 60/min quota).

query parameters

response

{
  "data": [
    {
      "id": "uuid",
      "url": "https://...",
      "type": "image",
      "mime_type": "image/jpeg",
      "width": 1080,
      "height": 1350,
      "size_bytes": 482113,
      "thumbnail_url": null,
      "filename": "desk.jpg",
      "description": "the product on a wooden desk next to a laptop",
      "source": "upload",
      "use_count": 2,
      "last_used_at": "ISO 8601 | null",
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 }
}

request body

response

{
  "data": {
    "added": [
      {
      "id": "uuid",
      "url": "https://...",
      "type": "image",
      "mime_type": "image/jpeg",
      "width": 1080,
      "height": 1350,
      "size_bytes": 482113,
      "thumbnail_url": null,
      "filename": "desk.jpg",
      "description": "the product on a wooden desk next to a laptop",
      "source": "upload",
      "use_count": 2,
      "last_used_at": "ISO 8601 | null",
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
    ]
  }
}

request body

response

{
  "data": {
      "id": "uuid",
      "url": "https://...",
      "type": "image",
      "mime_type": "image/jpeg",
      "width": 1080,
      "height": 1350,
      "size_bytes": 482113,
      "thumbnail_url": null,
      "filename": "desk.jpg",
      "description": "the product on a wooden desk next to a laptop",
      "source": "upload",
      "use_count": 2,
      "last_used_at": "ISO 8601 | null",
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
}

response

{
  "data": { "id": "uuid", "deleted": true }
}

query parameters

response

{
  "data": [
    {
      "id": "uuid",
      "name": "string",
      "persona_analysis": "object | null",
      "build_status": "idle|building|complete|error",
      "build_progress": 0,
      "build_started_at": "ISO 8601 | null",
      "build_error": "string | null",
      "last_analyzed_at": "ISO 8601 | null",
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 3, "total_pages": 1 }
}

request body

errors

errors

notes

• includes persona_analysis, persona_analysis_structured, custom_samples, twitter_samples, reddit_samples, facebook_samples, instagram_samples, tiktok_samples, linkedin_samples, brand_kit (omitted when unset)

request body

errors

errors

notes

• cannot delete if used by any launches

request body

response

{ "data": { "started": true, "persona_id": "uuid" } }

errors

notes

• listen for persona.analyzed webhook when complete

request body

response

{ "data": { "success": true, "analysis_limit": { "used": 1, "limit": 3, "remaining": 2 } } }

errors

notes

• free - usage was charged at analyze. call once build_status is ready_for_review

response

{ "data": { "success": true } }

errors

notes

• free - analyze usage is not refunded

response

{
  "data": {
    "configured": true,
    "config": {
      "enabled": true,
      "mode": "review",
      "platforms": ["twitter", "linkedin"],
      "formats": ["text", "visual"],
      "persona_id": "uuid | null",
      "posting_times": { "times": ["09:30", "17:30"], "days": [1, 2, 3, 4, 5] },
      "run_hour": 2,
      "timezone": "America/New_York",
      "product_url": "string | null",
      "product_image_url": "string | null",
      "product_brief": "string | null",
      "content_pillars": ["string"] | null,
      "directives": ["string"] | null,
      "min_queue": 7,
      "max_posts_per_day": 4,
      "track_links": false,
      "reuse_media": false,
      "media_source": "ai",
      "platform_settings": {},
      "paused": false,
      "pause_reason": null,
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    },
    "queued_ideas": 9,
    "pending_review": 3
  }
}

notes

• config is null until the first PATCH /autopilot call

request body

errors

notes

• posts created by autopilot consume your monthly launch limit
• visual and video formats also consume your monthly AI media limits

query parameters

response

{
  "data": [
    {
      "launch_id": "uuid",
      "hook": "string",
      "platform": "twitter",
      "format": "text",
      "content": "string | null",
      "reddit_title": "string | null",
      "scheduled_date": "ISO 8601 | null",
      "media_count": 0,
      "created_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 3, "total_pages": 1 }
}

notes

• each item is a draft launch - edit it first with PATCH /launches/:id if needed

response

{
  "data": { "launch_id": "uuid", "status": "scheduled", "scheduled_date": "ISO 8601" }
}

errors

notes

• a stale scheduled_date rolls forward to the next posting slot automatically

request body

response

{
  "data": { "launch_id": "uuid", "rejected": true }
}

errors

response

{
  "data": { "queued": true, "run_date": "2026-06-12" }
}

errors

notes

• steps that already completed today are skipped, so a manual run tops up rather than double-posts

query parameters

response

{
  "data": [
    {
      "run_date": "2026-06-12",
      "step": "schedule_slots",
      "status": "completed",
      "stats": { "created": 3, "slots": 4 },
      "error": null,
      "started_at": "ISO 8601",
      "completed_at": "ISO 8601"
    }
  ]
}

query parameters

response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "rec_type": "repost_winner",
      "status": "pending",
      "platform": "twitter",
      "launch_id": "uuid",
      "posting_log_id": "uuid",
      "payload": {
        "launch_name": "july feature drop",
        "post_url": "https://x.com/...",
        "score": 42.5,
        "baseline": 6
      },
      "score": 42.5,
      "baseline": 6,
      "expires_at": "ISO 8601",
      "applied_launch_id": null,
      "applied_at": null,
      "dismissed_at": null,
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 3, "total_pages": 1 }
}

notes

• rec_type is one of: repost_winner, cross_post, boost_winner, promote_winner, pause_underperformer
• recommendations expire automatically (default 14 days), act on them while the post is still riding

request body

response

{
  "success": true,
  "data": {
    "recommendation": { "id": "uuid", "rec_type": "repost_winner", "status": "applied", "...": "..." },
    "outcome": { "kind": "launch_draft", "launch_id": "uuid" }
  }
}

errors

notes

• repost_winner and cross_post create a DRAFT launch seeded with the winning content. nothing publishes until you schedule it
• boost_winner creates a PAUSED boost with the suggested budget. activate it separately to start spend
• promote_winner queues the winner into your autopilot queue (autopilot must be enabled)
• pause_underperformer adds a standing directive to your autopilot config

response

{
  "success": true,
  "data": { "id": "uuid", "rec_type": "repost_winner", "status": "dismissed", "...": "..." }
}

errors

request body

response

{
  "data": {
    "status": "processing",
    "job_id": "uuid",
    "fal_request_id": "string",
    "generation_type": "image",
    "usage": { "used": 3, "limit": 50, "remaining": 47 },
    "plan": "pro"
  }
}

errors

notes

• type 'script_video' generates a video from a text script (requires platform 'instagram' or 'tiktok' and an explicit prompt). type 'video' generates from a visual/cinematic prompt

response

{
  "data": {
    "id": "uuid",
    "generation_type": "image",
    "prompt": "...",
    "result_url": "https://cdn.dropspace.dev/...",
    "reference_image_url": "https://cdn.dropspace.dev/... | null",
    "status": "processing|completed|failed",
    "progress": 75,
    "model_id": "string",
    "error_message": "string | null",
    "launch_id": "uuid",
    "created_at": "ISO 8601",
    "completed_at": "ISO 8601 | null"
  }
}

errors

notes

• listen for media.ready webhook when status becomes completed

response

{
  "data": {
    "id": "uuid",
    "email": "you@example.com",
    "full_name": "string | null",
    "avatar_url": "string | null",
    "role": "user",
    "has_completed_onboarding": true,
    "created_at": "ISO 8601",
    "updated_at": "ISO 8601"
  }
}

errors

request body

response

{ "data": { "id": "uuid", "full_name": "string | null", "avatar_url": "string | null" } }

response

{ "data": { "url": "https://billing.stripe.com/session/..." } }

query parameters

response

{ "data": { "auth_url": "https://...", "state": "string" } }

errors

query parameters

response

{
  "data": [
    {
      "id": "uuid",
      "platform": "twitter",
      "entity_id": "string",
      "account_info": { "username": "...", "display_name": "..." },
      "account_type": "personal",
      "is_active": true,
      "expires_at": "ISO 8601 | null",
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 5, "total_pages": 1 }
}

notes

• connecting a new platform happens via the dashboard OAuth flow; use DELETE to disconnect
• every connection that has not been removed is listed, including dead ones. `is_active` is false once the token is invalidated (the moment the `connection.expired` webhook fires) and true again if the connection recovers (`connection.restored`, within 72 hours). read `is_active` to decide whether a connection works, not `expires_at` - that is the access token's own expiry, which dropspace refreshes routinely.

query parameters

response

{
  "data": { "message": "twitter disconnected successfully" }
}

errors

notes

• reconnect by re-running the OAuth flow from the dashboard or the in-app connect button
• omit `account_id` to disconnect every account on the platform; pass it to remove just one

response

{
  "data": {
    "platform": "youtube",
    "description": "weekly drops, behind the scenes, and launch-day streams."
  }
}

errors

notes

• the change is made on youtube itself via channels.update (50 quota units); the stored profile in GET /connections is refreshed at the same time.

response

{
  "data": {
    "platforms": [
      { "platform": "facebook", "connected": true, "account_name": "dropspace" },
      { "platform": "linkedin", "connected": true, "account_name": "dropspace" },
      { "platform": "twitter", "connected": true, "account_name": "@dropspace" },
      { "platform": "instagram", "connected": true, "account_name": "@dropspace" },
      { "platform": "tiktok", "connected": false },
      { "platform": "youtube", "connected": false }
    ],
    "connected_platforms": ["facebook", "linkedin", "twitter", "instagram"],
    "timestamp": "ISO 8601"
  }
}

notes

• always returns all 7 auto-post platforms in canonical order
• account_name is only present when connected and account info exists
• connected_platforms lists valid values for the dropspace_platforms field when creating launches
• checks is_active flag and token expiry from the database - does not perform live health checks

response

{
  "data": {
    "id": "uuid",
    "name": "my integration",
    "key_prefix": "ds_live_abc...",
    "scopes": ["read", "write", "generate", "send"],
    "created_at": "ISO 8601"
  }
}

notes

• no scope required - any valid API key can check its own permissions

response

{
  "data": [
    {
      "id": "uuid",
      "name": "my integration",
      "key_prefix": "ds_live_abc...",
      "scopes": ["read", "write", "generate", "send"],
      "last_used_at": "ISO 8601 | null",
      "revoked_at": "ISO 8601 | null",
      "created_at": "ISO 8601"
    }
  ]
}

request body

response

{
  "data": {
    "key": "ds_live_abc123...",
    "api_key": {
      "id": "uuid",
      "name": "my integration",
      "key_prefix": "ds_live_abc...",
      "scopes": ["read", "write", "generate", "send"],
      "created_at": "ISO 8601"
    }
  }
}

notes

• the full key is shown only once - store it securely

request body

response

{
  "data": {
    "id": "uuid",
    "name": "renamed key",
    "key_prefix": "ds_live_abc...",
    "last_used_at": "ISO 8601 | null",
    "revoked_at": "ISO 8601 | null",
    "created_at": "ISO 8601"
  }
}

errors

response

{
  "data": {
    "key": "ds_live_...",
    "api_key": { "id": "uuid", "name": "string", "key_prefix": "ds_live_abcd", "created_at": "ISO 8601" }
  }
}

notes

• requires the `admin` scope.
• the previous key stops working as soon as this returns.

errors

response

{
  "data": [
    {
      "id": "uuid",
      "url": "https://your-app.com/webhooks",
      "events": ["launch.completed", "launch.failed", "post.deleted"],
      "active": true,
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601",
      "consecutive_failures": 0,
      "disabled_at": null,
      "disabled_reason": null
    }
  ]
}

notes

• after 10 consecutive failed delivery attempts the endpoint is auto-disabled (active: false, disabled_reason set) and the account owner is emailed
• re-enable via PATCH /webhooks/:id with { "active": true }. this resets the failure counter

request body

response

{
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks",
    "events": ["launch.completed", "launch.failed", "post.deleted"],
    "secret": "a1b2c3d4...",
    "active": true,
    "consecutive_failures": 0,
    "disabled_at": null,
    "disabled_reason": null
  }
}

errors

notes

• the secret is shown only once - store it securely for signature verification
• available events: "launch.completed" (launch finished publishing), "launch.failed" (launch failed to publish), "launch.partial" (launch partially succeeded), "media.ready" (media generation completed), "persona.analyzed" (persona analysis completed), "post.deleted" (a published post was detected as deleted from its platform), "recommendation.created" (new recommendations were generated for the account), "connection.expired" (a connected account's token was invalidated and needs reauth), "connection.restored" (an expired connection is live again after a successful refresh - no reconnect needed)
• post.deleted payload: { "event": "post.deleted", "data": { "launch_id": "uuid", "platform": "twitter", "post_url": "https://...", "post_id": "12345", "deletion_reason": "not_found", "detected_at": "2025-01-15T10:30:00Z" } }
• connection.expired payload: { "event": "connection.expired", "data": { "platform": "instagram", "reason": "token_refresh_failed", "detected_at": "2026-02-18T12:00:00.000Z" } }
• connection.restored payload: { "event": "connection.restored", "data": { "platform": "instagram", "reason": "token refresh succeeded after an earlier deactivation", "restored_at": "2026-09-08T19:30:00.000Z" } } - dropspace re-tries a failed refresh for 72 hours after connection.expired; a connection still dead after that needs a reconnect
• deletion_reason values: not_found, gone, creator_deleted, moderation_removed, account_deleted, spam_filtered

response

{
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks",
    "events": ["launch.completed", "launch.failed", "post.deleted"],
    "active": true,
    "created_at": "ISO 8601",
    "updated_at": "ISO 8601",
    "consecutive_failures": 0,
    "disabled_at": null,
    "disabled_reason": null
  }
}

errors

request body

errors

errors

response

{
  "data": {
    "success": true,
    "delivery_id": "uuid",
    "response_status": 200,
    "response_body": "OK"
  }
}

errors

notes

• posts a `webhook.test` event signed with the webhook's secret to the registered URL
• returns the receiver's response status and a (truncated) response body for debugging
• creates a delivery row that shows up in `/webhooks/:id/deliveries`
• 10s timeout: `response_status: 408` indicates the receiver didn't respond in time

response

{
  "data": {
    "id": "uuid",
    "secret": "a1b2c3d4..."
  }
}

errors

notes

• the new secret is shown only once - update your verification code immediately
• the old secret becomes invalid immediately after rotation
• in-flight webhook deliveries (already queued) use the secret from enqueue time and are not affected

query parameters

response

{
  "data": [
    {
      "id": "uuid",
      "event_type": "launch.completed",
      "status": "delivered|pending|failed",
      "attempt_count": 1,
      "response_status": 200,
      "delivered_at": "ISO 8601",
      "failed_at": null,
      "next_retry_at": null,
      "created_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 12, "total_pages": 1 }
}

errors

notes

• `failed_at` is set on terminal failures (delivered_at and failed_at are mutually exclusive, mirroring iris). `next_retry_at` is null when QStash is handling retries opaquely.

response

{
  "data": {
    "plan": "starter",
    "billing_period": {
      "start": "ISO 8601",
      "end": "ISO 8601"
    },
    "limits": {
      "launches_per_month": { "limit": 50, "used": 3, "remaining": 47 },
      "ai_images_per_month": { "limit": 100, "used": 12, "remaining": 88 },
      "ai_videos_per_month": { "limit": 20, "used": 5, "remaining": 15 },
      "personas": { "limit": 10, "used": 2, "remaining": 8 },
      "analyses_per_persona": { "limit": 3 },
      "regenerations_per_launch": { "limit": 5 }
    },
    "features": {
      "can_connect_own_accounts": true,
      "can_post_to_official_accounts": true,
      "allowed_platforms": ["facebook", "linkedin", "twitter", "reddit", "instagram", "tiktok", "youtube"]
    }
  }
}

notes

• limit and remaining can be "unlimited" (string) instead of a number for higher-tier plans
• personas is a lifetime limit (not per billing period)
• analyses_per_persona and regenerations_per_launch are per-resource limits (no used/remaining tracking)

response

{
  "data": {
    "balance": 7,
    "packs": [
      { "id": "pack_20", "credits": 20, "price_usd": "12.00" }
    ],
    "purchase_endpoint": "POST /credits/purchase"
  }
}

notes

• returns balance 0 for x402 wallets and API key users (credits are MPP-only)
• balance is cached in Redis (5-min TTL) with database as source of truth

request body

response

{
  "data": {
    "credits_added": 20,
    "new_balance": 27,
    "pack": { "id": "pack_20", "credits": 20, "price_usd": "12.00" }
  }
}

errors

notes

• MPP agents only - x402 wallets are rejected with 400 (crypto has low fees already)
• the MPP credential must be for the pack price ($12.00 = 1200 cents), not the per-launch price
• credits never expire and are deducted automatically when creating launches
• the launch fee is charged once, when the launch is created, and covers the publishing attempt: a launch that ends partial or failed is not refunded. if creating the launch fails after payment, a used credit or free-tier launch is given back automatically; a per-launch x402 or MPP payment is not reversed automatically, so contact support with the request id.
• duplicate purchases with the same MPP credential are rejected (idempotent)

request body

response

{
  "data": {
    "id": "uuid",
    "launch_id": "uuid",
    "platform": "facebook",
    "post_id": "<page_id>_<post_id>",
    "status": "paused",
    "objective": "engagement",
    "daily_budget_cents": 500,
    "duration_days": 3,
    "meta_ad_account_id": "act_123",
    "meta_campaign_id": "1234567890",
    "meta_adset_id": "1234567891",
    "meta_ad_id": "1234567892",
    "impressions": null,
    "clicks": null,
    "reach": null,
    "link_clicks": null,
    "total_spend_cents": null,
    "stop_reason": null,
    "created_at": "ISO 8601",
    "activated_at": null,
    "ended_at": null
  }
}

errors

notes

• requires the launch to have a successful facebook post (post_id available in posting_logs).
• boost is created in PAUSED status. call POST /launches/{id}/boost/{boost_id}/activate to start spending.
• creative reuses the existing organic post via object_story_id, so no creative upload is required.
• meta enforces ad spend on the user's ad account. dropspace never holds card data for ad budgets.

response

{
  "data": [
    {
      "id": "uuid",
      "launch_id": "uuid",
      "status": "active",
      "daily_budget_cents": 500,
      "duration_days": 3,
      "impressions": 4320,
      "clicks": 87,
      "reach": 3211,
      "total_spend_cents": 1230
    }
  ]
}

errors

notes

• no payment required: boost was already paid for at create time.
• flips campaign → ad set → ad in order so the ad inherits ACTIVE status correctly.

notes

• idempotent: canceling a boost already in a terminal state returns the current row unchanged.
• if meta-side DELETE fails, the dropspace row is still soft-deleted (manual cleanup may be needed).

response

{
  "success": true,
  "data": [
    { "version": "1.0.0", "date": "2026-07-21", "type": "feature", "summary": "..." }
  ]
}