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)
{
  "data": {
    "id": "uuid",
    "name": "announcing our new feature",
    "status": "draft",
    "platforms": ["linkedin", "twitter", "reddit"],
    "scheduled_date": null,
    "created_at": "2026-03-25T12:00:00Z",
    "updated_at": "2026-03-25T12:00:00Z"
  }
}

// 200 (publish: true, wait: true)
{
  "data": {
    "id": "uuid",
    "name": "announcing our new feature",
    "status": "completed",
    "platforms": ["linkedin", "twitter"],
    "scheduled_date": null,
    "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
• 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`
• 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 requires `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
• 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 `publish` 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, TikTok requires privacy_level in tiktok_settings, TikTok video mode needs video, TikTok photo mode needs images, YouTube requires video, YouTube title ≤ 100 chars, YouTube description ≤ 5,000 chars

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

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,
          "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 are fetched live from platform APIs when stale (older than 5 minutes). calling this endpoint triggers a refresh automatically.
• fetched_at is the most recent timestamp when metrics were collected. next_refresh_at indicates when calling again could yield fresh data (fetched_at + 5 min).
• cache_status per platform: fresh (< 5 min old, from cache), refreshed (fetched from platform API), 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, comments, shares), Instagram (views, engagement, saved, likes, comments, shares), Reddit (score, upvotes, upvoteRatio, comments), TikTok (views, likes, comments, shares)
• 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",
      "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 'delete' scope on your API key (not included by default - add it in API key settings)
• 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 'delete' scope on your API key (not included by default - add it in API key settings)
• 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": [
    {
      "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, youtube_samples

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

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

• connections are managed via the dashboard OAuth flow - this endpoint is read-only

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": "reddit", "connected": false },
      { "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", "publish", "generate"],
    "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", "publish", "generate"],
      "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", "publish", "generate"],
      "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

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"
    }
  ]
}

request body

response

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

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)
• 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" } }
• 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"
  }
}

errors

request body

errors

errors

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",
      "attempts": 1,
      "response_status": 200,
      "delivered_at": "ISO 8601",
      "created_at": "ISO 8601"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 12, "total_pages": 1 }
}

errors

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 /v1/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
• if a launch creation fails after credit deduction, the credit is refunded automatically
• duplicate purchases with the same MPP credential are rejected (idempotent)