partner integration guide

the short version of how a product publishes for its own users through dropspace. read it in five minutes, then book a call to start. back to the partner overview.

overview

base url: https://api.dropspace.dev. paths below are relative to it, with no /v1 prefix on this host. every request sends Authorization: Bearer ds_live_..., with JSON in and out. a success is { "data": ... } and a failure is { "error": { "code", "message", "requestId" } }.

  • a creator is one of your users. each creator maps to a dropspace user and is keyed by your own external_creator_id.
  • the partner key calls the /partner/* routes: provision creators, start connections, pause and resume, register webhooks. keep it server-side.
  • a creator key is returned when you provision a creator. the creator publishes and reads its own data with it against the normal API (POST /launches, GET /audience, GET /connections). it never carries the partner scope.
  • partner and creator keys are shown once, when created or rotated. store them, because there is no read-back.

provision a creator

POST /partner/creators with the partner key. external_creator_id is required and your own id for the user. display_name and email are optional. provisioning is idempotent on external_creator_id.

curl -X POST https://api.dropspace.dev/partner/creators \
  -H "Authorization: Bearer ds_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_creator_id": "user_123", "display_name": "Ava Reyes" }'

the first call returns 201 with created: true, the creator, and the creator key. a repeat call returns 200 with created: false and no key. rotate a lost key with POST /partner/creators/{id}/keys/rotate. list creators with GET /partner/creators?page=1&page_size=20 (page size up to 100), or fetch one with GET /partner/creators/{id}, which includes its connected platforms and accounts.

connect accounts

POST /partner/creators/{id}/connections/{platform}/connect with the partner key. platform is one of instagram, tiktok, youtube, twitter (X), reddit, linkedin, facebook. it returns auth_url and state. open auth_urlin the creator's browser or webview. the creator's token is stored on their dropspace user.

curl -X POST https://api.dropspace.dev/partner/creators/cr_123/connections/instagram/connect \
  -H "Authorization: Bearer ds_live_..."

# returns { "data": { "auth_url": "...", "state": "..." } } -- open auth_url in the creator's browser or webview

when the creator finishes, dropspace sends them back to the product that started the connection. a mobile app gets a deep link built from the url scheme registered for your account, with a fixed oauth-callback host:

<your_scheme>://oauth-callback?platform=<platform>&status=success
<your_scheme>://oauth-callback?platform=<platform>&status=error&message=<url-encoded>

handle that path: the host is always oauth-callback and is not configurable. a website gets a redirect to the web return address registered for your account, with the same three values as query parameters:

<your_web_return_address>?platform=<platform>&status=success
<your_web_return_address>?platform=<platform>&status=error&message=<url-encoded>

the web return address is registered with dropspace when you are onboarded and cannot be passed per request: the connect endpoint takes no redirect_url, and a client-supplied redirect is ignored. if your product has both an app and a site, register both and choose per connect with an optional body, { "return": "web" } or { "return": "app" }. without a body, an account with an app scheme returns to the app, and an account with only a web address returns to the site. branch on status and show message on an error.

status and message are hints for your user interface, not proof. render message as plain text, never as markup, and confirm the connection through the API (the connections listing) before you treat an account as connected: anyone can open your return address with query parameters of their choosing.

some accounts need to qualify before the platform's consent screen will accept them:

  • instagram: a Business or Creator account. personal accounts are not supported by Instagram's API. no linked Facebook Page is needed.
  • facebook: a Facebook Page. posts go to a Page, never to a personal profile.
  • youtube: a channel on the account, and every YouTube post must carry a video.
  • tiktok, twitter, reddit, linkedin: a standard account is enough. LinkedIn can also post to a company page.

to add a second account on a platform, run connect again and have the creator authorize a different account. it is stored as an additional account for instagram, tiktok, youtube, twitter, and reddit.

publish for a creator

the creator publishes with its own key against POST /launches. the partner key is not involved in posting. title (up to 200 characters) and platforms are required.

curl -X POST https://api.dropspace.dev/launches \
  -H "Authorization: Bearer ds_live_..." \
  -H "Idempotency-Key: spring-drop-user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "spring drop",
    "platforms": ["instagram", "twitter"],
    "user_platform_accounts": { "instagram": "<connection id>", "twitter": "<connection id>" },
    "platform_contents": {
      "instagram": { "content": "..." },
      "twitter": { "content": "..." }
    },
    "media": [{ "source": "url", "url": "https://example.com/clip.mp4" }],
    "publish": true
  }'
  • user_platform_accounts maps each target platform to a connection id from GET /connections. a bare key (instagram) is the creator's primary account there. a composite key (instagram:<account_id>) targets one of several. Facebook posts name a Page (facebook:page:<page_id>). LinkedIn takes linkedin:personal or linkedin:organization:<org_id>.
  • per-platform content goes in platform_contents[<platform>], with platform settings (for example youtube_settings, tiktok_settings, and a post_type on Instagram and Facebook for feed or story posts) alongside content.
  • media is sent as a url or base64 and ingested during the create call, so a url only has to work for that one request. a media failure comes back as a 4xx on create. limits: up to 10 items, up to 9 images (5 MB each) and 1 video (512 MB); base64 is capped at 4 MB.
  • publish: true is what sends the post. without it the launch is stored and nothing publishes it until you call POST /launches/{id}/publish. add wait: true to get per-platform results in the response.
  • a create that fails to publish still returns 201, with the reason in a publish_error object. check for it on every create.
  • send an Idempotency-Key header and retry with the same key after a timeout. a retry while the first request runs gets 409 with Retry-After, and a finished request returns the original 201 for 24 hours.
  • status is at GET /launches/{id}/status. retry a failed platform with POST /launches/{id}/retry. a platform you list with no connected account fails with NO_ACCOUNT, so that launch reads partial.

to schedule instead, omit publish and send scheduled_date as ISO 8601 with any offset. it must be at least 15 minutes ahead, and the launch must carry its posting accounts. a scheduled launch can be cancelled, moved, or edited with PATCH /launches/{id} until it fires.

curl -X POST https://api.dropspace.dev/launches \
  -H "Authorization: Bearer ds_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "spring drop",
    "platforms": ["instagram"],
    "user_platform_accounts": { "instagram": "<connection id>" },
    "platform_contents": { "instagram": { "content": "..." } },
    "media": [{ "source": "url", "url": "https://example.com/clip.mp4" }],
    "scheduled_date": "2026-12-01T08:00:00-04:00"
  }'

analytics and comments

  • GET /launches/{id}/analyticsreturns each post's live metrics: views, likes, comments, and platform-specific extras. counts are fetched from each platform and cached. a post reads cache_status: "unavailable" right after publishing or when a platform permission is missing, so poll again shortly after.
  • GET /launches/{id}/commentsreturns each post's top-level comments, newest first. each post carries a status (ok, unsupported, comments_disabled, post_deleted, unavailable), so branch on it. comment text is available for YouTube and Instagram.
  • reply with POST /launches/{id}/comments/replies (YouTube and Instagram). hide, unhide, and delete comments are Instagram only.
  • GET /audience returns follower counts and growth for instagram, tiktok, youtube, twitter, and facebook. YouTube growth reaches back about 30 days.

pause, resume, offboard

  • PATCH /partner/creators/{id} with { "status": "paused" } or { "status": "active" }. a paused creator cannot publish or read audience data (403), and connect is refused. their connections are kept, so resuming needs no new sign-in. connections paused 90 or more consecutive days may need the creator to reconnect.
  • DELETE /partner/creators/{id} offboards a creator: it revokes their keys. re-provisioning the same external_creator_idreactivates them with a fresh key. offboarding revokes API keys, not the creator's social connections.

webhooks

register one endpoint for your whole integration with POST /partner/webhooks (partner key), passing url and events. it receives events for every creator you own. the response includes a secret that signs each delivery and is shown once. list with GET /partner/webhooks, remove with DELETE /partner/webhooks/{id} (up to 10).

  • events: connection.expired, connection.restored, launch.completed, launch.failed, launch.partial, media.ready, persona.analyzed, post.deleted, recommendation.created.
  • connection.expiredfires when a creator's token is invalidated, so you can prompt them to reconnect. connection.restored retracts it when a platform-side problem clears. a reason of meta_deauthorize is final: the creator removed dropspace themselves.
  • the envelope is id, event, timestamp, created_at, data, and partner deliveries add a creator object with the dropspace id and your external_creator_id.
  • headers: X-Dropspace-Signature (hex HMAC-SHA256), X-Dropspace-Timestamp (unix seconds), and X-Dropspace-Delivery (stable across retries, use it to dedupe).

the signed string is the timestamp, a literal dot, then the raw body. compare against the raw body before parsing it, and reject timestamps older than 5 minutes.

const expected = crypto.createHmac("sha256", secret).update(`${tsHeader}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sigHeader));

rate limits

  • creator key: 60 requests per minute, per creator. one creator never uses another's budget.
  • partner key: 3,000 requests per minute, shared across your account, because every connect goes through it.
  • connect is also capped at 20 per minute per creator, and provisioning at 300 per minute. over-rate calls return 429 with Retry-After: wait and continue. provisioning is idempotent, so re-running a failed batch is safe.
  • every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. limits can be raised for your account on request.

platform limitations

these are what the platforms do not provide, so dropspace cannot either. plan your product around them.

  • Instagram comment posting. a first comment on publish exists for Reddit only. there is no Instagram equivalent.
  • Facebook analytics. per-post metrics are reactions, likes, comments, and shares. there are no impressions or reach, and Facebook story metrics are unavailable.
  • Instagram analytics. impressions and reach are no longer available from Instagram for anyone. you get views, likes, comments, and saves. Instagram story insights are available only while the story is live.
  • TikTok comments.TikTok's API exposes comment counts only, so comment text is not available. counts are in analytics.
  • comment moderation. hiding, unhiding, and deleting comments is Instagram only, and replies are YouTube and Instagram only.
  • profile edits.editing a connected account's profile on the platform works for the YouTube channel description only.
  • null is not zero. a metric a platform does not disclose is null. show it as unavailable, never as zero.

getting access

onboarding starts with a call. dropspace issues your partner key and registers where the connect flow returns to: your app's url scheme, your website's return address, or both. after that you can provision creators right away.

book a call to get started