dropspace

Create and publish social media launches via the Dropspace API. Use when user wants to post to social media, create launches, manage personas, generate media, track post analytics, schedule content, or anything Dropspace-related. Supports 10 platforms (Twitter, LinkedIn, Reddit, Instagram, TikTok, Facebook, YouTube, Substack, Product Hunt, Hacker News) with per-post analytics and AI content generation.

# Dropspace API Skill

Multi-platform social media publishing with AI-generated content, media generation, per-post analytics, and persona-based writing styles.

## Setup

Set your API key:
```bash
export DROPSPACE_API_KEY="ds_live_..."  # from dropspace.dev/settings/api
```

Base URL: `https://api.dropspace.dev`
Auth header: `-H "Authorization: Bearer $DROPSPACE_API_KEY"`

Also available as MCP server: `npx @jclvsh/dropspace-mcp`
Machine-readable docs: [llms.txt](https://www.dropspace.dev/llms.txt) | [OpenAPI](https://www.dropspace.dev/openapi.json)

## API Key Scopes

Keys can be scoped: `read`, `write`, `delete`, `publish`, `generate`, `admin`.

| Use Case | Recommended Scopes |
|----------|-------------------|
| AI agents / MCP | read, write, generate |
| CI/CD publishing | read, publish |
| Monitoring / dashboards | read |
| Full access (admin tools) | all scopes |

Missing scope returns 403 with `AUTH_002`.

## Audit Logging

Destructive/sensitive API operations are automatically logged: delete launch/persona, publish, create/revoke key, create/delete/rotate webhook.

## Supported Platforms

twitter, linkedin, reddit, instagram, tiktok, facebook, producthunt, hackernews, substack

### Per-Platform Character Limits
Twitter 280/tweet (25,000 for X Premium) × 6 tweets (use `thread` array or `content` string), 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

## Core Workflow: Create & Publish

### 1. Check connected platforms
```bash
# User's OAuth connections
curl -s https://api.dropspace.dev/connections \
  -H "Authorization: Bearer $DROPSPACE_API_KEY"

# Official Dropspace accounts available for posting
curl -s https://api.dropspace.dev/dropspace/status \
  -H "Authorization: Bearer $DROPSPACE_API_KEY"
```
Connections: OAuth-connected accounts with platform, username, account_type, is_active, expires_at. Managed via dashboard.
Dropspace status: Shows which official Dropspace accounts (facebook, linkedin, twitter, reddit, instagram, tiktok) are connected and available for the `dropspace_platforms` field.

### 2. Create a launch (AI generates platform-specific content)
```bash
curl -s -X POST https://api.dropspace.dev/launches \
  -H "Authorization: Bearer $DROPSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "launch title",
    "product_description": "what to post about (1-2000 chars)",
    "platforms": ["twitter", "linkedin", "reddit"],
    "product_url": "https://optional-url.com",
    "persona_id": "optional-uuid",
    "scheduled_date": "optional ISO 8601 (≥15 min future)",
    "publish": "optional boolean — immediately publish after creation (returns 202, mutually exclusive with scheduled_date, requires write+publish scopes)",
    "wait": "optional boolean — wait for publishing to complete and return post URLs inline (requires publish: true, returns 200 with posting_status)",
    "dropspace_platforms": ["twitter"],
    "user_platform_accounts": {"twitter": "account-id"},
    "media": [
      {"source": "url", "url": "https://example.com/image.png"},
      {"source": "base64", "data": "iVBOR...", "filename": "slide.png", "mime_type": "image/png"}
    ],
    "media_attach_platforms": ["twitter", "linkedin"],
    "media_mode": "images|video",
    "generate_ai_videos": ["instagram", "tiktok"],
    "custom_content": "single text for all platforms (validated against lowest char limit)",
    "custom_content_reddit_title": "reddit title when using custom_content (max 300 chars)",
    "platform_contents": {
      "twitter": {"thread": ["tweet 1", "tweet 2", "tweet 3"]},
      "reddit": {"title": "...", "content": "..."},
      "linkedin": {"content": "custom post"},
      "tiktok": {
        "content": "caption text",
        "tiktok_settings": {
          "privacy_level": "PUBLIC_TO_EVERYONE",
          "auto_add_music": true,
          "allow_comments": true,
          "allow_duet": true,
          "allow_stitch": true
        }
      }
    }
  }'
```
Content auto-generated via Claude from description + scraped URL + persona.

**Content options (mutually exclusive):**
- Omit both → full AI generation for all platforms
- `platform_contents` → per-platform custom content. Platforms without content get AI-generated. Reddit requires `title`. Product Hunt/HN support optional `title` (max 60/80 chars). **Twitter supports `thread` (string[], each ≤280 chars or ≤25,000 for X Premium, max 6 tweets) instead of `content`** — mutually exclusive with `content`.
- `custom_content` → `string` distributed to all platforms (validated against most restrictive char limit), or `string[]` to create a Twitter thread (each ≤280 chars or ≤25,000 for X Premium, max 6) that joins with double newlines for other platforms. Array form requires Twitter in platforms. Use `custom_content_reddit_title` if Reddit is included.

**`user_platform_accounts` key format:**
- Simple keys: `"twitter"`, `"reddit"`, `"instagram"`, `"tiktok"`
- LinkedIn personal: `"linkedin:personal"` → personal profile
- LinkedIn org: `"linkedin:organization:<org_id>"` → company page
- Facebook page: `"facebook:page:<page_id>"`
- Multiple keys allowed (e.g. post to personal + org simultaneously)

**TikTok settings (`platform_contents.tiktok.tiktok_settings`):**
- `privacy_level` (REQUIRED before publishing): `"PUBLIC_TO_EVERYONE"`, `"FOLLOWER_OF_CREATOR"`, `"MUTUAL_FOLLOW_FRIENDS"`, or `"SELF_ONLY"`
- Optional booleans: `allow_comments`, `allow_duet`, `allow_stitch`, `is_commercial`, `is_your_brand`, `is_branded_content`, `auto_add_music`
- Branded content (`is_branded_content: true`) cannot use `SELF_ONLY` privacy
- Can be set at creation or updated via PATCH (deep-merged)

**Inline media upload (`media` field):** Upload images/videos inline via URL or base64 — server handles storage upload and populates `media_assets` in the response. Max 10 items (9 images + 1 video). Images: jpeg/png/webp/gif (5MB). Videos: mp4/mov (512MB via URL, 4MB via base64). `media_attach_platforms` and `media_mode` auto-inferred if not set. Mutually exclusive with `media_assets`.

**Pre-uploaded media (`media_assets` field):** For files already in storage — requires `id`, `url`, `type`, `filename`, `size`, `mime_type`. Mutually exclusive with `media`.

Media limits: Instagram/Facebook 10, Reddit 20, TikTok 35.

**Inline publish (`publish` + `wait` fields):**
- `publish: true` → immediately publish after creation (returns 202). Mutually exclusive with `scheduled_date`. Requires both `write` and `publish` scopes.
- `wait: true` (requires `publish: true`) → wait for publishing to complete synchronously and return 200 with `posting_status` containing per-platform results and post URLs. Typical wait: 10-30s for text platforms, up to 60s+ with Instagram/TikTok.
- If publish validation fails after creation, returns 201 with `publish_error: { code, message }` — retry via `POST /launches/:id/publish`.

**Publish validation (LAUNCH_007):** When publishing fails validation, the response includes a `details` array listing all blocking issues. Checks include: char limits (all platforms), Reddit title ≤300 chars, Reddit video needs video+thumbnail, Reddit images need images, Instagram reel needs video, Instagram carousel needs ≥2 images, TikTok requires `tiktok_settings.privacy_level`, TikTok video needs video, TikTok photo needs images.
Instagram requires media. TikTok requires video or photos.
`generate_ai_videos`: subset of `["instagram", "tiktok"]` — generates video scripts and starts async rendering.
`media_mode`: `"images"` or `"video"` (auto-inferred when using `media`).

Upload errors: `UPLOAD_001` (unsupported type), `UPLOAD_002` (too large), `UPLOAD_003` (storage upload failed).

### 3. Review & edit content
```bash
# Edit specific platform content:
curl -s -X PATCH https://api.dropspace.dev/launches/LAUNCH_ID \
  -H "Authorization: Bearer $DROPSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform_contents