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 webviewwhen 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_accountsmaps each target platform to a connection id fromGET /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 takeslinkedin:personalorlinkedin:organization:<org_id>.- per-platform content goes in
platform_contents[<platform>], with platform settings (for exampleyoutube_settings,tiktok_settings, and apost_typeon Instagram and Facebook for feed or story posts) alongsidecontent. - 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: trueis what sends the post. without it the launch is stored and nothing publishes it until you callPOST /launches/{id}/publish. addwait: trueto get per-platform results in the response.- a create that fails to publish still returns
201, with the reason in apublish_errorobject. check for it on every create. - send an
Idempotency-Keyheader and retry with the same key after a timeout. a retry while the first request runs gets409withRetry-After, and a finished request returns the original201for 24 hours. - status is at
GET /launches/{id}/status. retry a failed platform withPOST /launches/{id}/retry. a platform you list with no connected account fails withNO_ACCOUNT, so that launch readspartial.
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 readscache_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 astatus(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 /audiencereturns 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 sameexternal_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.restoredretracts it when a platform-side problem clears. a reason ofmeta_deauthorizeis final: the creator removed dropspace themselves.- the envelope is
id, event, timestamp, created_at, data, and partner deliveries add acreatorobject with the dropspace id and yourexternal_creator_id. - headers:
X-Dropspace-Signature(hex HMAC-SHA256),X-Dropspace-Timestamp(unix seconds), andX-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
429withRetry-After: wait and continue. provisioning is idempotent, so re-running a failed batch is safe. - every response carries
X-RateLimit-Limit,X-RateLimit-Remaining, andX-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