# dropspace

dropspace is a SaaS platform for multi-platform content distribution. create launches with AI-generated content, generate images and videos, manage writing personas, and publish to Twitter, Reddit, LinkedIn, Facebook, Instagram, TikTok, and more.

website: https://www.dropspace.dev
docs: https://www.dropspace.dev/docs
API: https://api.dropspace.dev

## key features

- multi-platform publishing to 9+ social networks in one click
- AI content generation tailored per platform (tone, length, format)
- AI image and video generation for launch visuals
- brand personas to maintain distinct voices across platforms
- developer REST API with granular scopes and webhooks
- MCP server for AI agent integration (36 tools across 9 categories)
- x402 crypto payments for autonomous agent workflows
- launch scheduling with timezone support
- per-platform content customization and preview

## supported platforms

| platform | posting | notes |
|----------|---------|-------|
| Facebook | automated | page posts with images and links |
| LinkedIn | automated | personal profiles and company pages |
| Twitter / X | automated | tweets and threads |
| Reddit | automated | multi-subreddit with community-aware content |
| Instagram | automated | photo posts with optimized captions |
| TikTok | automated | short-form video content |
| Product Hunt | manual (guided) | taglines, descriptions, maker comments |
| Hacker News | manual (guided) | Show HN posts with technical framing |

## platform guides

### Facebook

reach millions on Facebook with AI-crafted posts

dropspace helps you publish on Facebook with AI-generated posts optimized for engagement. craft compelling page posts, reach wider audiences, and manage your Facebook presence alongside every other platform — all from one dashboard.

**features:**

- AI-optimized page posts: generate Facebook posts tailored for maximum engagement with smart formatting, compelling hooks, and audience-aware language.
- multi-format content: create text posts, image posts, and link shares — all optimized for Facebook's algorithm and engagement patterns.
- audience reach insights: understand how your content performs on Facebook with integrated analytics and engagement tracking.
- cross-platform scheduling: schedule your Facebook posts to go live alongside Twitter, LinkedIn, Reddit, and more — all at the perfect time.
- AI persona matching: your AI persona ensures every Facebook post matches your brand voice, keeping your messaging consistent across platforms.

**tips:**

- use images or videos — Facebook posts with visual content get 2.3x more engagement than text-only posts
- keep posts concise — the ideal Facebook post length is 40-80 characters for maximum engagement
- post during peak hours — Facebook engagement peaks on weekdays between 9 AM and 2 PM
- ask questions to spark comments — the algorithm rewards posts that generate conversations

### LinkedIn

establish thought leadership on LinkedIn with AI-powered posts

dropspace generates professional LinkedIn posts that position you as a thought leader. publish content that resonates with a professional audience, build credibility, and drive meaningful B2B engagement.

**features:**

- professional tone optimization: AI crafts LinkedIn posts with the right professional tone — authoritative but approachable, informative but engaging.
- thought leadership framing: transform announcements into industry insights. dropspace frames your content as valuable professional thought leadership.
- engagement-optimized formatting: smart line breaks, strategic emoji usage, and hook-first structures that drive engagement in the LinkedIn feed.
- company page support: post from both personal profiles and company pages to maximize your reach across your professional network.
- hashtag strategy: AI selects relevant professional hashtags that increase discoverability without looking spammy.
- cross-platform publishing: coordinate your LinkedIn post with Twitter, Reddit, and other platforms for unified multi-channel distribution.

**tips:**

- lead with a strong hook — the first two lines determine whether people click 'see more'
- use line breaks generously — walls of text get scrolled past on LinkedIn
- share personal context or a story to humanize your announcement
- post on Tuesday through Thursday mornings for peak B2B engagement
- tag relevant people and companies to expand your reach beyond your network

### Twitter / X

go viral on Twitter / X with AI-generated content

dropspace creates Twitter / X posts designed to go viral. craft engaging tweets and threads with AI-optimized hooks, smart character limits, and engagement-first formatting — then post alongside every other platform in one click.

**features:**

- smart character optimization: AI packs maximum impact into Twitter's character limits. every word earns its place with compelling, concise copy.
- thread generation: automatically break longer announcements into engaging tweet threads with hooks that keep readers scrolling.
- engagement-first hooks: AI writes opening lines designed to stop the scroll. data-driven hooks that maximize retweets and replies.
- hashtag optimization: smart hashtag selection that increases discoverability without cluttering your tweet. quality over quantity.
- multi-platform sync: publish on Twitter alongside LinkedIn, Reddit, Instagram, and more — all from your dropspace dashboard.

**tips:**

- front-load your best content — the first line is everything on Twitter
- use threads for launches with multiple features or benefits to share
- engage with replies quickly after posting — early engagement signals boost reach
- include one clear call-to-action rather than multiple competing asks
- post between 8-10 AM and 6-9 PM for maximum visibility

### Reddit

reach engaged communities on Reddit with authentic, AI-crafted posts

dropspace generates Reddit posts that respect community norms while sharing your content authentically. AI crafts value-first posts tailored for specific subreddits — no spam, no self-promotion flags, just genuine engagement.

**features:**

- subreddit-aware content: AI adapts your content to match the tone, rules, and expectations of each target subreddit.
- authentic voice generation: Reddit hates marketing speak. AI generates posts that sound like a genuine community member sharing something valuable.
- community rules compliance: smart content generation that avoids common self-promotion pitfalls and respects subreddit-specific posting rules.
- value-first framing: your content is framed around the problem it solves, not the product itself — the approach that performs best on Reddit.
- multi-subreddit targeting: create tailored versions of your announcement for different subreddits, each with the right tone and angle.

**tips:**

- lead with value — explain the problem you solve before mentioning your product
- read the subreddit rules carefully — each community has unique self-promotion policies
- engage genuinely in comments after posting to build trust with the community
- avoid marketing language — Reddit users can spot promotional content instantly
- build karma in your target subreddits before launch day for better posting privileges

### Instagram

create stunning Instagram content with AI-generated captions and visuals

dropspace creates Instagram content that captivates your audience. generate scroll-stopping captions with optimized hashtags, pair them with AI-generated visuals, and publish alongside every other platform.

**features:**

- caption optimization: AI writes Instagram captions with engaging hooks, strategic line breaks, and calls-to-action that drive profile visits and link clicks.
- hashtag strategy: smart mix of popular and niche hashtags to maximize discoverability without getting lost in oversaturated tags.
- AI visual generation: generate eye-catching launch visuals with AI. create product shots, announcement graphics, and carousel-ready images.
- caption formatting: proper formatting with line breaks, emoji placement, and structure that looks great in the Instagram feed.
- cross-platform coordination: sync your Instagram post with Twitter, LinkedIn, Facebook, and more for cohesive multi-platform distribution.

**tips:**

- use AI-generated images to create polished visuals — Instagram rewards high-quality visual content
- put the most important info in the first line — most users see only the preview before tapping 'more'
- use 20-30 relevant hashtags in a mix of popular and niche tags for optimal discoverability
- post between 11 AM and 1 PM or 7-9 PM for peak Instagram engagement

### TikTok

go viral on TikTok with AI-powered short-form content

dropspace helps you create TikTok-ready content with AI-generated videos, trending hooks, and engagement-optimized captions. reach a massive audience with short-form content designed for the for you page.

**features:**

- AI video generation: generate short-form videos with AI. create product demos, announcement clips, and attention-grabbing visuals.
- trending hook optimization: AI writes opening hooks based on what's working on TikTok right now — grab attention in the first second.
- caption and hashtag strategy: optimized captions with trending hashtags and sounds references to maximize for you page placement.
- short-form content design: content structured for TikTok's fast-paced format. concise, punchy, and designed to keep viewers watching.
- multi-platform publishing: coordinate your TikTok posts with Instagram, Twitter, LinkedIn, and more from one dashboard.

**tips:**

- hook viewers in the first second — TikTok's algorithm prioritizes watch time above everything else
- keep videos under 60 seconds for the best chance at for you page placement
- use trending sounds and formats to ride existing algorithmic momentum
- post consistently — TikTok rewards creators who publish regularly
- show the product in action rather than talking about features

### Product Hunt

nail your Product Hunt launch with AI-optimized content

dropspace prepares you for a successful Product Hunt launch with AI-generated taglines, descriptions, and maker comments. plan your launch day strategy, optimize your listing, and coordinate with posts on every other platform.

**features:**

- tagline optimization: AI generates and refines taglines that capture your product's value in the few words that matter most on Product Hunt.
- description crafting: compelling product descriptions that highlight your unique value proposition and drive upvotes from the PH community.
- maker comment strategy: AI helps plan your maker comments — the behind-the-scenes story that PH users love and that drives engagement.
- launch day coordination: coordinate your Product Hunt listing with posts on Twitter, LinkedIn, and Reddit for maximum launch day visibility.

**tips:**

- launch at 12:01 AM PST to get a full day of voting — timing is critical on Product Hunt
- prepare your maker comment ahead of time — tell the story behind why you built the product
- keep your tagline under 60 characters and focus on the core value proposition
- coordinate supporters to visit and engage within the first hour for algorithmic boost
- respond to every comment on your launch — PH rewards active makers

### Hacker News

reach the tech community on Hacker News with compelling posts

dropspace helps you craft Hacker News submissions that resonate with the technical community. AI generates titles optimized for HN's audience, focusing on technical merit and genuine value rather than marketing fluff.

**features:**

- title optimization: AI crafts HN titles that are descriptive, honest, and technically focused — the style that performs best with the HN community.
- technical audience framing: content framed for developers and tech enthusiasts. focus on technical innovation, architecture decisions, and real results.
- discussion generation: titles and descriptions designed to spark thoughtful technical discussion — the key to staying on the front page.
- show HN formatting: properly formatted Show HN posts that follow community conventions and guidelines for project showcases.

**tips:**

- use 'Show HN:' prefix for project showcases — it's the accepted format for sharing your own work
- keep titles factual and descriptive — avoid superlatives and marketing language
- be ready to answer technical questions in the comments — HN values maker engagement
- share what makes your approach technically interesting, not just what the product does
- post between 8-11 AM EST for maximum US audience visibility

## how-to guides

### how to launch on Reddit with dropspace

a step-by-step guide to launching on Reddit using dropspace's AI-powered content generation and multi-subreddit posting.

difficulty: beginner | estimated time: 10 minutes

**steps:**

1. **create your account & connect Reddit** — sign up for dropspace and navigate to settings to connect your Reddit account via OAuth. dropspace will request the minimum permissions needed to post on your behalf.
   tip: make sure your Reddit account has enough karma and age to post in your target subreddits. most subreddits require at least a few weeks of account history.
2. **create a new launch** — head to your dashboard and create a new launch. give it a name, add a description of your product, and optionally upload images or generate AI media.
3. **configure Reddit settings** — select which subreddits you want to post to. dropspace lets you choose from popular launch subreddits or enter custom ones. each subreddit gets its own tailored post.
   tip: research each subreddit's rules before launching. some have specific formatting requirements or restrict self-promotion to certain days.
4. **generate AI content** — use dropspace's AI to generate persona-aware content for each subreddit. the AI adapts tone and style — casual for r/SideProject, technical for r/webdev, and narrative-driven for r/startups.
5. **review and customize content** — review the generated content for each subreddit. edit titles, body text, and flair as needed. dropspace shows you a preview of how each post will appear.
6. **schedule or publish immediately** — choose to publish right away or schedule your launch for the optimal time. dropspace handles posting to all selected subreddits simultaneously.

### automate LinkedIn posts with AI

learn how to connect LinkedIn and use AI personas to generate professional, platform-optimized content for your posts.

difficulty: beginner | estimated time: 8 minutes

**steps:**

1. **connect your LinkedIn account** — go to settings and connect your LinkedIn account. dropspace supports both personal profiles and company pages through OAuth.
2. **create a persona for professional tone** — set up an AI persona that matches your professional brand voice. configure it for thought leadership, industry expertise, or a casual-professional hybrid.
   tip: analyze your best-performing LinkedIn posts and describe that style to your persona. the AI will learn to match it.
3. **create a launch** — create a new launch with your product details. include a clear value proposition and any supporting data or metrics — LinkedIn audiences respond well to specifics.
4. **generate AI content optimized for LinkedIn** — let dropspace generate LinkedIn-specific content. the AI structures posts with hooks, bullet points, and calls-to-action that perform well in LinkedIn's algorithm.
5. **review the professional formatting** — check the generated post for proper LinkedIn formatting: short paragraphs, line breaks for readability, relevant hashtags, and a compelling opening line.
6. **publish** — publish your launch. dropspace posts to LinkedIn along with any other platforms you've configured, all from a single click.

### set up webhook notifications for your launches

configure webhook endpoints to receive real-time notifications when launches are published, media is generated, and more.

difficulty: intermediate | estimated time: 15 minutes

**steps:**

1. **navigate to developer settings** — go to your dropspace settings and find the developer section. you'll need an API key — create one if you haven't already.
2. **create a webhook endpoint** — add a new webhook by providing your endpoint URL. this should be a publicly accessible HTTPS URL that can receive POST requests.
   tip: for local development, use a tunneling service like ngrok to expose your local server to the internet.
3. **configure event types** — select which events you want to receive: launch.published, launch.completed, launch.failed, media.completed, persona.completed, and more. start with just the events you need.
4. **test with a sample event** — use the test button to send a sample payload to your endpoint. verify that your server receives and acknowledges the request with a 200 status code.
5. **handle webhook payloads in your app** — parse the incoming JSON payload in your application. each event type has a specific payload structure documented in the API reference.
6. **verify webhook signatures** — validate the X-Webhook-Signature header using HMAC-SHA256 with your webhook secret. this ensures the request genuinely came from dropspace.
   tip: always use timing-safe comparison when verifying signatures to prevent timing attacks.

### create your first dropspace API integration

build a complete integration with the dropspace API — from authentication to creating launches, generating content, and monitoring via webhooks.

difficulty: intermediate | estimated time: 20 minutes

**steps:**

1. **create an API key with appropriate scopes** — navigate to developer settings and create a new API key. select the scopes you need: launches:read, launches:write, personas:read, media:read, and webhooks:manage.
   tip: follow the principle of least privilege — only request the scopes your integration actually needs.
2. **install the SDK or set up HTTP client** — install the @jclvsh/dropspace-mcp package for a type-safe client, or use any HTTP client to call the REST API directly at api.dropspace.dev.
3. **authenticate requests** — include your API key in the Authorization header as a Bearer token: Authorization: Bearer ds_live_... — all API requests require this header.
4. **create a launch via API** — make a POST request to /v1/launches with your launch name, description, and target platforms. the API returns the created launch with its ID for subsequent operations.
5. **generate content for the launch** — call POST /v1/launches/{id}/generate-content to trigger AI content generation. optionally specify a persona ID to use your brand voice. content is generated asynchronously.
6. **trigger publishing** — when your content is ready, call POST /v1/launches/{id}/publish to start publishing across all configured platforms. the API returns immediately while publishing happens in the background.
7. **monitor via webhooks** — set up webhooks (see the webhook guide) to receive launch.published and launch.completed events. this lets your integration react in real-time without polling.

### schedule your first multi-platform post

learn how to create a launch, generate AI content for multiple platforms, and schedule it to publish at the perfect time.

difficulty: beginner | estimated time: 5 minutes

**steps:**

1. **create a new launch** — from your dashboard, click 'new launch' and give it a name. describe what you want to share — a product update, thought piece, announcement, or campaign.
2. **select your platforms** — choose which platforms to publish to. dropspace supports Facebook, LinkedIn, Twitter, Reddit, Instagram, TikTok, and more.
   tip: connect your platform accounts in settings first if you haven't already.
3. **generate AI content** — click generate to let AI create platform-optimized content. each platform gets tailored copy — professional for LinkedIn, concise for Twitter, visual-first for Instagram.
4. **review and edit** — review the generated content for each platform. edit anything that doesn't sound right — you're always in control of the final message.
5. **schedule or publish** — choose to publish immediately or schedule for a specific date and time. dropspace handles posting to all selected platforms simultaneously.
   tip: weekday mornings tend to see higher engagement across most platforms.

### create a brand persona for your agency

set up AI personas to manage multiple brand voices — perfect for agencies, ghostwriters, and anyone managing content for multiple clients.

difficulty: beginner | estimated time: 8 minutes

**steps:**

1. **navigate to personas** — go to the personas section in your dashboard. this is where you create and manage all your brand voices.
2. **create a new persona** — click 'new persona' and give it a name that identifies the brand or client. add a description of the voice, tone, and style you want the AI to emulate.
   tip: include examples of the brand's existing content to help the AI match the voice more accurately.
3. **configure voice attributes** — define the persona's tone (professional, casual, witty), target audience, industry, and any specific terminology or phrases the brand uses.
4. **run AI analysis** — let AI analyze the persona configuration and build a voice profile. this takes a few seconds and creates a reusable template for all future content.
5. **test with a launch** — create a test launch and select your new persona. generate content and verify the AI output matches the brand voice you configured.
6. **repeat for each client** — create a separate persona for each brand or client you manage. when creating launches, simply select the appropriate persona to switch voices instantly.

### automate posting with Claude Code + MCP

connect dropspace to Claude Code using the MCP server and automate content creation, scheduling, and publishing from your terminal.

difficulty: intermediate | estimated time: 15 minutes

**steps:**

1. **get your API key** — go to settings in the dropspace dashboard and create a new API key. select the scopes you need: launches:read, launches:write, content:write, and publish:write.
   tip: follow the principle of least privilege — only request the scopes your automation needs.
2. **configure the MCP server** — add the dropspace MCP server to your Claude Code configuration at ~/.claude/settings.json. set the DROPSPACE_API_KEY environment variable to your API key.
3. **verify the connection** — open Claude Code and ask it to 'list my dropspace launches'. if the MCP server is configured correctly, it will use the dropspace tools to fetch your launches.
4. **create a launch via Claude Code** — ask Claude Code to 'create a new dropspace launch about [your topic]'. the assistant will use the MCP tools to create the launch and generate content.
5. **generate and review content** — ask Claude Code to generate content for your launch. review the AI-generated posts for each platform and request edits if needed.
6. **publish from your terminal** — when the content is ready, ask Claude Code to publish the launch. it will trigger publishing across all configured platforms.

## comparisons

### dropspace vs Buffer

the AI-powered alternative to Buffer

**differentiators:**

- AI content generation: dropspace generates unique, platform-optimized content for every launch. Buffer focuses on scheduling — you still write everything yourself.
- multi-platform launch: publish across 9+ platforms simultaneously with one click. Buffer is built for scheduling posts, not coordinating cross-platform content.
- developer API: integrate publishing into your CI/CD pipeline or build custom workflows with the dropspace API. Buffer's API is read-heavy with limited write access.
- AI personas: create AI personas that match your brand voice across every platform. Buffer has no equivalent feature.
- x402 payments: monetize your content with built-in x402 payment support. Buffer has no native payment integration.

**verdict:** Buffer is a great scheduling tool, but dropspace is purpose-built for multi-platform content with AI. if you need AI-generated content, developer APIs, and multi-platform coordination, dropspace is the clear choice.

### dropspace vs Hootsuite

the modern alternative to Hootsuite

**differentiators:**

- no enterprise complexity: dropspace is simple and focused. Hootsuite's sprawling feature set means steep learning curves and features you'll never use.
- AI-native, not bolted on: AI content generation is core to dropspace, not a paid add-on. Hootsuite charges extra for AI capabilities.
- transparent pricing: dropspace starts free with clear upgrade paths. Hootsuite starts at $99/mo with no free tier.
- developer-first: full API access, webhook notifications, and MCP integration for developers who want to automate their publishing.

**verdict:** Hootsuite is built for enterprise social media teams. dropspace is built for creators and developers who want to publish fast with AI-powered content — at a fraction of the cost.

### dropspace vs Later

more than just scheduling — AI-powered launching

**differentiators:**

- content-focused, not just scheduling: dropspace coordinates multi-platform content distribution. Later focuses on visual content scheduling for Instagram and TikTok.
- AI content per platform: generate platform-optimized content automatically. Later's AI features are limited to caption suggestions.
- developer API: full REST API with webhooks and MCP integration. Later has no public developer API.
- Reddit & Hacker News support: publish on developer-focused platforms that Later doesn't support. reach the audiences that matter for technical content.

**verdict:** Later excels at visual content scheduling for Instagram and TikTok. dropspace is the better choice for multi-platform content, especially if you need developer platforms like Reddit and Hacker News, plus AI-generated content.

## frequently asked questions

### launches

**Q: how do I create a launch?**

go to the launches page and click the create button. you can add a title, description, and media content. once ready, select which platforms to post to and either publish immediately or schedule it for later.

**Q: can I schedule a launch for a specific time?**

yes, when creating or editing a launch, you can set a scheduled date and time. dropspace will automatically publish your launch to all selected platforms at the scheduled time.

**Q: what happens if a platform fails during publishing?**

dropspace publishes to each platform independently. if one platform fails, the others will still be published successfully. you can retry failed platforms from the launch detail page.

**Q: can I edit a launch after publishing?**

you can edit the launch content in dropspace, but changes won't be reflected on platforms where it was already posted. social media platforms generally don't support editing published posts via API.

### platform connections

**Q: which platforms does dropspace support?**

dropspace supports Facebook, LinkedIn (personal and company pages), Twitter/X, Reddit, Instagram, and TikTok for automated posting. Product Hunt and Hacker News are supported for manual posting with guided instructions.

**Q: how do I connect a social media account?**

go to settings and find the platform connections section. click connect next to the platform you want to add. you'll be redirected to the platform's OAuth page to authorize dropspace.

**Q: why is my platform connection showing as unhealthy?**

platform connections can become unhealthy if your access token expires or if you revoke access on the platform's side. go to settings, disconnect the platform, and reconnect it to refresh the token.

**Q: can I connect multiple accounts for the same platform?**

currently, you can connect one account per platform. for LinkedIn, you can connect both a personal profile and a company page as separate connections.

### AI content generation

**Q: how does AI content generation work?**

dropspace uses AI to generate platform-optimized text content for your launches. it adapts the tone, length, and format for each platform (e.g., shorter for Twitter, more detailed for LinkedIn).

**Q: can I generate images and videos with AI?**

yes, dropspace supports AI image generation and AI video generation. you can generate images from text prompts and create short video content for your launches.

**Q: how do I control the tone of generated content?**

use personas to define your brand voice. create a persona in the personas section with your preferred tone, style, and key messaging points. when generating content, select your persona to guide the AI output.

**Q: are there limits on AI generation?**

yes, AI generation usage is based on your plan. check your current usage and limits in the settings page under billing. you can upgrade your plan for higher limits.

### personas & brand voice

**Q: what is a persona?**

a persona represents your brand voice and style preferences. it includes your tone, target audience, key themes, and messaging guidelines. the AI uses this context to generate content that sounds like you.

**Q: how do I create a persona?**

go to the personas page and click create. you can describe your brand, provide example content, and define your target audience. the AI will analyze these inputs to build a comprehensive brand voice profile.

**Q: can I have multiple personas?**

yes, you can create multiple personas for different brands, products, or communication styles. select the appropriate persona when generating content for a launch.

### billing & plans

**Q: what plans are available?**

dropspace offers multiple plans with different limits for launches, AI generations, and platform connections. visit the settings page to see current plan options and pricing.

**Q: how do I upgrade or change my plan?**

go to settings and click on the billing section. you can upgrade, downgrade, or manage your subscription through the Stripe customer portal.

**Q: what happens when I reach my plan limits?**

when you reach a limit (e.g., monthly launches or AI generations), you'll see a notification. you can either wait for your billing period to reset or upgrade to a higher plan for more capacity.

**Q: can I cancel my subscription?**

yes, you can cancel anytime from the billing section in settings. your access continues until the end of your current billing period.

### developer API

**Q: does dropspace have an API?**

yes, dropspace offers a REST API for developers. you can create and manage launches, trigger publishing, and manage personas programmatically. visit the API documentation page for details.

**Q: how do I get an API key?**

go to settings and find the API keys section. click create to generate a new API key. make sure to copy and store it securely — it's only shown once.

**Q: is there a rate limit on the API?**

yes, API requests are rate-limited based on your plan. the current limits are shown in the API documentation. rate limit headers are included in every response.

### troubleshooting

**Q: my launch failed to publish — what should I do?**

check the launch detail page for specific error messages per platform. common issues include expired tokens (reconnect the platform), content policy violations (review your content), or rate limits (wait and retry).

**Q: I'm getting a 'token expired' error**

go to settings, disconnect the affected platform, and reconnect it. this will refresh your access token. if the issue persists, the platform may have revoked your app authorization.

**Q: images aren't uploading to a platform**

check that your image meets the platform's requirements (file size, dimensions, format). some platforms have stricter limits. try using a standard JPEG or PNG under 5MB.

**Q: the scheduled launch didn't publish**

scheduled launches require an active platform connection at the time of publishing. check that your connected accounts are still healthy in settings. also verify the scheduled time was set in your correct timezone.

## blog

### why cross-posting matters (and how to do it right)

published: 2026-03-04 | 6 min read

reaching your audience means being where they are. learn why cross-platform publishing is essential and how to tailor content for each platform without burning out.

read more: https://www.dropspace.dev/blog/why-cross-posting-matters

### managing multiple brands with personas

published: 2026-03-04 | 5 min read

how agencies, ghostwriters, and multi-brand teams use dropspace personas to maintain distinct brand voices across every platform.

read more: https://www.dropspace.dev/blog/managing-multiple-brands-with-personas

### announcing x402 payments for autonomous agents

published: 2026-03-04 | 5 min read

dropspace now supports the x402 protocol for machine-to-machine payments, enabling AI agents to authenticate, pay per request, and run autonomous launch workflows.

read more: https://www.dropspace.dev/blog/x402-payments-autonomous-agents

### introducing the dropspace MCP server

published: 2026-02-20 | 4 min read

the @jclvsh/dropspace-mcp package brings 36 tools across 9 categories to Claude Code, Cursor, and other MCP-compatible AI coding assistants.

read more: https://www.dropspace.dev/blog/dropspace-mcp-server

### dropspace developer API v1

published: 2026-02-17 | 6 min read

programmatic access to dropspace with API keys, granular scopes, AI content generation, webhook notifications, and comprehensive error codes.

read more: https://www.dropspace.dev/blog/developer-api-v1

---

# API documentation

## base URL

```
https://api.dropspace.dev
```

## authentication

all requests require a bearer token:

```
Authorization: Bearer ds_live_...
```

create API keys at https://dropspace.dev/settings under the API section.

## scopes

API keys support scoped permissions. assign only the scopes your integration needs.

| scope | description |
|-------|-------------|
| read | view launches, personas, media, and connections |
| write | create and update launches and personas |
| delete | delete launches and personas |
| publish | publish and retry launches |
| generate | AI content and media generation |
| admin | manage API keys and webhooks |

default scopes (if none specified): read, write, publish, generate.

## endpoints

### launches

create, manage, and publish launches across multiple platforms.

#### GET /launches

list launches with pagination (supports x402 wallet auth)

**query parameters:**

| name | type | required | description |
|------|------|----------|-------------|
| page | integer | no | page number (default: 1) |
| page_size | integer (1–100) | no | items per page (default: 50) |

**response (200):**

```json
{
  "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 }
}
```

#### POST /launches

create a launch with AI-generated or custom content (supports x402 wallet auth)

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| title | string (1–200 chars) | yes | launch title |
| product_description | string (1–2000 chars) | yes | product description — used as context for AI generation and stored with the launch |
| platforms | string[] (1–9) | yes | target platforms |
| product_url | URL | no | product URL (scraped for context) |
| scheduled_date | ISO 8601 | no | schedule for future (≥ 15 min from now) |
| persona_id | UUID | no | writing style persona to use |
| dropspace_platforms | string[] | no | post via dropspace official accounts |
| user_platform_accounts | object | no | map of platform key → token_id (UUID). most platforms use simple keys: "twitter", "reddit", "instagram", "tiktok". LinkedIn uses "linkedin:personal" for personal profiles or "linkedin:organization:<org_id>" for company pages. Facebook uses "facebook:page:<page_id>". multiple keys allowed (e.g. post to personal + org simultaneously) |
| media | array | no | inline media upload — each item is either `{ source: "url", url: "https://..." }` to fetch from a URL, or `{ source: "base64", data: "...", filename: "photo.jpg", mime_type: "image/jpeg" }` for raw data. the server uploads to storage and populates media_assets automatically. mutually exclusive with media_assets. max 10 items (9 images + 1 video). images: jpeg, png, webp, gif (5MB). videos: mp4, mov (512MB via URL, 4MB via base64). when provided, media_attach_platforms and media_mode are auto-inferred if not set |
| media_assets | array | no | pre-uploaded media objects (id, url, type, filename, size, mime_type). mutually exclusive with media |
| media_attach_platforms | string[] | no | platforms to attach media to (subset of platforms). auto-inferred from selected platforms when using media |
| media_mode | "images" | "video" | no | media mode for the launch. auto-inferred from media types when using media |
| generate_ai_videos | ["instagram", "tiktok"] subset | no | platforms to generate AI videos for |
| platform_contents | object | no | pre-written content per platform — each value needs `content` (string). for Twitter, you can alternatively provide `thread` (string[], each ≤ 280 chars, max 6 tweets) instead of `content` — mutually exclusive with `content`. Reddit requires `title` (string, max 300 chars). Product Hunt and Hacker News support an optional `title` field (max 60 and 80 chars respectively). TikTok supports a `tiktok_settings` object with `privacy_level` (required before publishing: "PUBLIC_TO_EVERYONE", "FOLLOWER_OF_CREATOR", "MUTUAL_FOLLOW_FRIENDS", or "SELF_ONLY") and optional booleans: `allow_comments`, `allow_duet`, `allow_stitch`, `is_commercial`, `is_your_brand`, `is_branded_content`, `auto_add_music`. when provided, AI content generation is skipped. per-platform character limits are enforced: Twitter 280/tweet × 6 tweets, LinkedIn 3,000, Instagram 2,200, Reddit 3,000, Facebook 3,000, TikTok 4,000, Product Hunt 500, Hacker News 2,000, Substack 3,000. mutually exclusive with custom_content |
| custom_content | string | string[] | no | single text distributed to all selected platforms, or array of tweet strings when twitter is selected. string form is validated against the most restrictive platform limit. array form creates a twitter thread (each ≤280 chars, max 6) and consolidates for other platforms. mutually exclusive with platform_contents. when provided, AI content generation is skipped |
| custom_content_reddit_title | string (max 300 chars) | no | reddit post title — required when using custom_content with reddit in platforms |

**response (201):**

```json
{
  "data": {
    "id": "uuid",
    "name": "announcing our new feature",
    "status": "draft",
    "platforms": ["twitter", "linkedin", "reddit"],
    "platform_contents": {
      "twitter": { "content": "1/ Tired of spending hours...", "platform": "twitter" },
      "linkedin": { "content": "Excited to share...", "platform": "linkedin" },
      "reddit": { "title": "Show r/dropspaceapp: ...", "content": "...", "platform": "reddit" },
      "tiktok": { "content": "...", "platform": "tiktok", "tiktok_settings": { "privacy_level": "PUBLIC_TO_EVERYONE", "allow_comments": true } }
    },
    "media_assets": [],
    "media_attach_platforms": ["twitter", "linkedin"]
  }
}
```

**errors:**

- 400 SERVER_002: validation error
- 400 UPLOAD_001: unsupported media type
- 400 UPLOAD_002: media file too large
- 400 UPLOAD_003: media storage upload failed
- 400 LAUNCH_007: platform requirements not met (e.g. Instagram/TikTok need media)
- 404 SERVER_003: persona not found
- 429 LAUNCH_002: plan launch limit reached
- 429 RATE_001: content generation rate limit

**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, max 6 tweets. mutually exclusive with `content`
- if a platform in generate_ai_videos already has a video_script in platform_contents, video script generation is skipped for that platform
- media is distributed to selected platforms with per-platform limits (Instagram/Facebook: 10, Reddit: 20, TikTok: 35)
- if generate_ai_videos is set, video scripts are generated and rendering begins asynchronously
- 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

#### GET /launches/:id

get a single launch with posting status (supports x402 wallet auth)

**response (200):**

```json
{
  "data": {
    "id": "uuid",
    "name": "string",
    "status": "completed",
    "platforms": ["twitter", "linkedin"],
    "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:**

- 404 LAUNCH_001: launch not found

#### PATCH /launches/:id

update a draft/scheduled/cancelled launch

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| scheduled_date | ISO 8601 | null | no | schedule for future (≥ 15 min from now), null to unschedule |
| status | "draft" | "manual" | "trigger" | "scheduled" | "cancelled" | no | update launch status |
| platforms | string[] | no | target platforms for this launch |
| name | string | no | launch name/title (max 200 chars) |
| product_description | string | no | product description (max 10,000 chars) |
| product_url | string | no | product URL (empty string to clear) |
| persona_id | string | null | no | persona ID for content generation, null to clear |
| platform_contents | object | no | per-platform content update (deep-merged with existing) — fields you include replace the old value, omitted fields are preserved. for Twitter, you can use `thread` (string[], each ≤ 280 chars, max 6) instead of `content` — mutually exclusive with `content`. Reddit `title` is optional (existing title preserved if omitted; max 300 chars if provided). Product Hunt and Hacker News support an optional `title` field (max 60 and 80 chars respectively). TikTok `tiktok_settings` can be set or updated here (deep-merged) — see POST docs for field details. per-platform character limits are enforced: Twitter 280/tweet × 6 tweets, LinkedIn 3,000, Instagram 2,200, Reddit 3,000, Facebook 3,000, TikTok 4,000, Product Hunt 500, Hacker News 2,000, Substack 3,000 |
| user_platform_accounts | object | no | map of platform key → token_id (UUID). most platforms use simple keys: "twitter", "reddit", "instagram", "tiktok". LinkedIn uses "linkedin:personal" for personal profiles or "linkedin:organization:<org_id>" for company pages. Facebook uses "facebook:page:<page_id>". multiple keys allowed (e.g. post to personal + org simultaneously) |
| dropspace_platforms | string[] | no | post via dropspace official accounts |
| media | array | no | inline media upload — same format as create. replaces existing media. mutually exclusive with media_assets |
| media_assets | array | no | pre-uploaded media objects. replaces existing media. mutually exclusive with media |
| media_attach_platforms | string[] | no | platforms to attach media to. auto-inferred when using media |
| media_mode | "images" | "video" | no | media mode. auto-inferred when using media |

**errors:**

- 400 UPLOAD_001: unsupported media type
- 400 UPLOAD_002: media file too large
- 400 UPLOAD_003: media storage upload failed
- 404 LAUNCH_001: launch not found
- 409 LAUNCH_003: cannot update a running, completed, or partial launch

**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
- 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, 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. just `privacy_level`) without overwriting the rest

#### DELETE /launches/:id

delete a launch (any status except running)

**response:** 204 no content

**errors:**

- 409 LAUNCH_003: cannot delete a launch that is currently running
- 404 LAUNCH_001: launch not found

#### POST /launches/:id/publish

queue launch for publishing (async) (supports x402 wallet auth)

**response (202):**

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

**errors:**

- 404 LAUNCH_001: launch not found
- 422 LAUNCH_007: launch has no platforms configured for posting
- 400 LAUNCH_007: platform requirements not met — see errors array for details
- 409 LAUNCH_004: launch is not in a publishable state or already publishing
- 403 AUTH_002: plan restriction (own accounts or dropspace accounts)

**notes:**

- the launch transitions to running — poll /status or listen for launch.completed / launch.failed 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, 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

#### POST /launches/:id/retry

retry failed platforms only

**response (202):**

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

**errors:**

- 404 LAUNCH_001: launch not found
- 400 LAUNCH_003: no failed platforms to retry
- 409 LAUNCH_004: launch is already running

#### POST /launches/:id/retry-content

retry content generation for failed platforms

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| platforms | string[] | no | filter to specific platforms |

**response (200):**

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

**errors:**

- 400 SERVER_002: no failed platforms to retry
- 404 LAUNCH_001: launch not found
- 429 LAUNCH_002: per-launch regeneration limit reached
- 429 RATE_001: content generation rate limit

#### POST /launches/:id/generate-content

regenerate AI content for all or specific platforms

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| platforms | string[] | no | platforms to regenerate (defaults to all) |
| generate_video_scripts | ["instagram", "tiktok"] subset | no | generate video scripts for these platforms |

**response (200):**

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

**errors:**

- 400 SERVER_002: no product_description or platforms
- 404 LAUNCH_001: launch not found
- 409 LAUNCH_003: launch is running/completed/partial
- 429 RATE_001: content generation rate limit
- 503 SERVER_001: content generation unavailable

**notes:**

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

#### GET /launches/:id/status

detailed posting logs per platform (supports x402 wallet auth)

**response (200):**

```json
{
  "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:**

- 404 LAUNCH_001: launch not found

#### GET /launches/:id/analytics

publishing analytics with per-post engagement metrics (live refresh)

**response (200):**

```json
{
  "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",
        "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",
        "metrics": {
          "score": 156,
          "upvotes": 200,
          "upvoteRatio": 0.78,
          "comments": 34,
          "fetched_at": "2026-02-22T09:58:00Z"
        }
      }
    ]
  }
}
```

**errors:**

- 404 LAUNCH_001: launch not found

**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 (just fetched from platform API), stale (rate limited or no token, returning older data), unavailable (no data exists).
- 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)

#### DELETE /launches/:id/posts/:logId

delete a single published post from its platform

**response (200):**

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

**errors:**

- 404 LAUNCH_001: launch not found
- 404 SERVER_003: posting log not found or not deletable
- 200 DELETE_NOT_SUPPORTED: platform does not support API deletion (Instagram, TikTok) — returned in response body, not as HTTP error

**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

#### DELETE /launches/:id/posts

delete all published posts for a launch from their platforms

**response (200):**

```json
{
  "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:**

- 404 LAUNCH_001: launch not found

**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

### personas

manage AI writing personas for content generation.

#### GET /personas

list personas with pagination

**query parameters:**

| name | type | required | description |
|------|------|----------|-------------|
| page | integer | no | page number (default: 1) |
| page_size | integer (1–100) | no | items per page (default: 50) |

**response (200):**

```json
{
  "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 }
}
```

#### POST /personas

create a new persona

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| name | string (1–100 chars) | yes | persona name |

**errors:**

- 409 SERVER_009: duplicate persona name
- 429 PERSONA_001: persona creation limit reached

#### GET /personas/:id

get persona with all writing samples

**errors:**

- 404 PERSONA_002: persona not found

**notes:**

- includes persona_analysis, persona_analysis_structured, custom_samples, twitter_samples, reddit_samples, facebook_samples, instagram_samples, tiktok_samples, linkedin_samples

#### PATCH /personas/:id

update name and/or writing samples

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| name | string (1–100 chars) | no | persona name |
| custom_samples | array (max 50) | no | custom writing samples |
| twitter_samples | array (max 50) | no | Twitter writing samples |
| reddit_samples | array (max 50) | no | Reddit writing samples |
| facebook_samples | array (max 50) | no | Facebook writing samples |
| instagram_samples | array (max 50) | no | Instagram writing samples |
| tiktok_samples | array (max 50) | no | TikTok writing samples |
| linkedin_samples | array (max 50) | no | LinkedIn writing samples |

**errors:**

- 404 PERSONA_002: persona not found
- 409 SERVER_009: duplicate persona name

#### DELETE /personas/:id

delete a persona

**response:** 204 no content

**errors:**

- 404 PERSONA_002: persona not found
- 422 SERVER_005: persona in use by launches

**notes:**

- cannot delete if used by any launches

#### POST /personas/:id/analyze

trigger AI persona analysis (async)

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| platforms | string[] | no | which platforms to analyze |
| include_custom_samples | boolean | no | include custom samples in analysis (default: false) |

**response (202):**

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

**errors:**

- 404 PERSONA_002: persona not found
- 409 SERVER_009: already building
- 429 PERSONA_003: persona build limit reached

**notes:**

- listen for persona.analyzed webhook when complete

### media

generate AI images and videos for your launches.

#### POST /media/generate

submit an image or video generation job

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| type | "image" | "video" | "script_video" | yes | generation type |
| launch_id | UUID | yes | associated launch |
| platform | string | yes | required for script_video: "instagram" or "tiktok" |
| prompt | string (10–2000 chars) | no | generation prompt (required for script_video) |
| product_description | string | no | product context |
| options.aspect_ratio | "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | no | aspect ratio (image supports all 10; video/script_video only supports 16:9 and 9:16) |
| options.duration_seconds | 4 | 6 | 8 | no | video duration (default: 8) |
| reference_image_url | URL | no | URL of a reference image for style/composition guidance (image type only, uses edit endpoint) |

**response (202):**

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

**errors:**

- 403 AUTH_002: plan doesn't include media generation
- 404 LAUNCH_001: launch not found or not owned
- 429 MEDIA_001: monthly media generation limit reached
- 429 RATE_001: concurrency limit reached

**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

#### GET /media/:jobId

poll media generation status

**response (200):**

```json
{
  "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:**

- 404 SERVER_003: media job not found

**notes:**

- listen for media.ready webhook when status becomes completed

### connections

view your OAuth platform connections (read-only).

#### GET /connections

list your OAuth platform connections

**query parameters:**

| name | type | required | description |
|------|------|----------|-------------|
| page | integer | no | page number (default: 1) |
| page_size | integer (1–100) | no | items per page (default: 50) |

**response (200):**

```json
{
  "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

### dropspace

check which official dropspace accounts are connected and available for posting.

#### GET /dropspace/status

check which official dropspace accounts are connected

**response (200):**

```json
{
  "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 }
    ],
    "connected_platforms": ["facebook", "linkedin", "twitter", "instagram"],
    "timestamp": "ISO 8601"
  }
}
```

**notes:**

- always returns all 6 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

### API keys

manage your API keys for authentication.

#### GET /keys/me

get the current API key's info

**response (200):**

```json
{
  "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

#### GET /keys

list all API keys

**response (200):**

```json
{
  "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"
    }
  ]
}
```

#### POST /keys

create a new API key (max 10)

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| name | string (1–100 chars) | yes | key name |
| scopes | string[] | no | permission scopes (default: read, write, publish, generate). available: read, write, delete, publish, generate, admin |

**response (201):**

```json
{
  "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

#### PATCH /keys/:id

rename an API key

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| name | string (1–100 chars) | yes | new key name |

**response (200):**

```json
{
  "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:**

- 404 SERVER_003: api key not found
- 409 SERVER_009: an api key with this name already exists

#### DELETE /keys/:id

revoke an API key

**response:** 204 no content

**errors:**

- 404 SERVER_003: api key not found

### webhooks

manage webhook endpoints for event notifications.

#### GET /webhooks

list webhook endpoints

**response (200):**

```json
{
  "data": [
    {
      "id": "uuid",
      "url": "https://your-app.com/webhooks",
      "events": ["launch.completed", "launch.failed"],
      "active": true,
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ]
}
```

#### POST /webhooks

create a webhook endpoint (max 10)

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| url | HTTPS URL | yes | webhook delivery URL |
| events | string[] | yes | event types to subscribe to |

**response (201):**

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

**errors:**

- 400 SERVER_002: invalid webhook url or events
- 400 SERVER_002: maximum 10 webhook endpoints allowed

**notes:**

- the secret is shown only once — store it securely for signature verification

#### GET /webhooks/:id

get a webhook endpoint

**response (200):**

```json
{
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks",
    "events": ["launch.completed", "launch.failed"],
    "active": true,
    "created_at": "ISO 8601",
    "updated_at": "ISO 8601"
  }
}
```

**errors:**

- 404 SERVER_003: webhook not found

#### PATCH /webhooks/:id

update url, events, or active status

**request body (JSON):**

| name | type | required | description |
|------|------|----------|-------------|
| url | HTTPS URL | no | new webhook URL |
| events | string[] | no | new event subscriptions |
| active | boolean | no | enable/disable endpoint |

**errors:**

- 404 SERVER_003: webhook not found
- 400 SERVER_002: invalid webhook url or events

#### DELETE /webhooks/:id

delete a webhook endpoint

**response:** 204 no content

**errors:**

- 404 SERVER_003: webhook not found

#### POST /webhooks/:id/rotate-secret

rotate the signing secret (new secret shown once)

**response (200):**

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

**errors:**

- 404 SERVER_003: webhook not found

**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

#### GET /webhooks/:id/deliveries

list delivery attempts with pagination

**query parameters:**

| name | type | required | description |
|------|------|----------|-------------|
| page | integer | no | page number (default: 1) |
| page_size | integer (1–100) | no | items per page (default: 50) |

**response (200):**

```json
{
  "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:**

- 404 SERVER_003: webhook not found

### usage

check your current plan, billing period, and usage limits.

#### GET /usage

get plan limits and current usage (supports x402 wallet auth)

**response (200):**

```json
{
  "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"]
    }
  }
}
```

**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)

## x402 payments

autonomous agents with crypto wallets can use the dropspace API without accounts or subscriptions via the x402 payment protocol (https://www.x402.org).

**how it works:**
- wallet users get 3 free launch creations/month using official dropspace accounts
- beyond the free tier, each launch creation costs $0.50 USDC on Base (eip155:8453)
- publishing, reading, and status checks are always free
- payments are verified via an x402 facilitator and settled on-chain only when needed
- wallet users can only post to official dropspace accounts

**supported endpoints:** GET /launches, POST /launches, GET /launches/:id, PATCH /launches/:id, DELETE /launches/:id, POST /launches/:id/publish, GET /launches/:id/status

**authentication:** include an `X-PAYMENT` header with a base64-encoded x402 payment proof.
the payment proof identifies your wallet. payment is only settled for launch creations beyond the free tier.
if you have no payment proof, the endpoint returns 402 with x402 pricing details.

**rate limit:** 30 requests/minute per wallet address.

## MCP server

the dropspace MCP server lets AI agents manage launches, personas, media, connections, API keys, webhooks, and more. 36 tools across 9 categories (launches, posts, personas, media, connections, API keys, webhooks, dropspace, usage).

```bash
npx -y @jclvsh/dropspace-mcp
```

set the DROPSPACE_API_KEY environment variable to your API key.
recommended scopes for AI agents: read, write, generate.

## OpenAPI spec

OpenAPI 3.1 spec available at: https://dropspace.dev/openapi.json

## error codes

all errors return: `{ error: { code, message } }`

### authentication

| code | HTTP | description |
|------|------|-------------|
| AUTH_001 | 401 | invalid or revoked API key |
| AUTH_002 | 403 | plan restriction (feature not available) |

### launches

| code | HTTP | description |
|------|------|-------------|
| LAUNCH_001 | 404 | launch not found |
| LAUNCH_002 | 429 | launch or regeneration limit exceeded |
| LAUNCH_003 | 409 | invalid launch status for operation |
| LAUNCH_004 | 409 | launch cannot be published from current status |
| LAUNCH_007 | 400 | platform requirements not met |

### personas

| code | HTTP | description |
|------|------|-------------|
| PERSONA_001 | 429 | persona creation limit reached |
| PERSONA_002 | 404 | persona not found |
| PERSONA_003 | 429 | persona build limit reached |

### media

| code | HTTP | description |
|------|------|-------------|
| MEDIA_001 | 429 | monthly media generation limit reached |

### uploads

| code | HTTP | description |
|------|------|-------------|
| UPLOAD_001 | 400 | unsupported media type (allowed: jpeg, png, webp, gif, mp4, mov) |
| UPLOAD_002 | 400 | media file too large (images: 5MB, videos: 512MB URL / 4MB base64) |
| UPLOAD_003 | 400 | media storage upload failed |

### payment (x402)

| code | HTTP | description |
|------|------|-------------|
| PAYMENT_001 | 402 | payment required (free tier exceeded) |
| PAYMENT_002 | 402 | payment verification failed |

### rate limiting

| code | HTTP | description |
|------|------|-------------|
| RATE_001 | 429 | too many requests |

### validation & server

| code | HTTP | description |
|------|------|-------------|
| SERVER_001 | 500 | internal server error |
| SERVER_002 | 400 | validation error |
| SERVER_003 | 404 | resource not found |
| SERVER_004 | 405 | method not allowed |
| SERVER_005 | 400 | invalid input format or business rule violation |
| SERVER_008 | 500 | database error |
| SERVER_009 | 409 | conflict (e.g. status transition race) |