Connect links

Create a connect link

POSThttps://hivepost.app/v1/connect-links

A page where your customer connects their own account. Send them to url: it is only in this answer, because it holds the link's secret. return_url must be https on a domain you added under Developers → Connect links (that host or a subdomain of it). Only networks open in the API can be asked for (403 network_not_available). The link works once and expires after 7 days. When it is used we send account.connected with your external_id, and the customer goes back to return_url?status=connected&account_id=…&external_id=… (or status=cancelled). Replaying the same Idempotency-Key returns the same link with a new url while it is open; the earlier url stops working.

Send an Idempotency-Key header. If the request times out and you send it again with the same key, you get the first answer instead of a second link. How it works

Headers

Idempotency-Keystring
1–255 printable characters. The same key within 24 hours returns the first response.

Body

external_idstringRequired
Your own id for this customer. It comes back on the account and in account.connected. Up to 255 characters.
networksarray of string
Networks the customer can connect. Today only Bluesky is open. Up to 8 items. Default ["bluesky"].
One of instagram, facebook, tiktok, youtube, linkedin, threads, pinterest, bluesky
return_urlstringRequired
https, on one of your allowed return domains. Up to 2,000 characters.
brand_idstring
The brand the account joins. Needed when the workspace has more than one brand.

Returns

201 Created.

Errors

Status	Code	When
400	`validation_failed`	The body isn't JSON, or the Idempotency-Key header isn't valid (`validation_failed`).
401	`unauthorized`	No API key, or one that isn't valid (`unauthorized`).
403	`forbidden`, `drafts_only`, `network_not_available`	The key can't do this (`forbidden`, `drafts_only`), or the network isn't open in the API (`network_not_available`).
409	`idempotency_conflict`	The Idempotency-Key was used for a different request, or its first request is still running (`idempotency_conflict`).
413	`payload_too_large`	The body is over 64 KB (`payload_too_large`).
422	`validation_failed`, `return_url_not_allowed`, `account_not_connected`, `text_too_long`, `media_required`, `time_in_past`	A field is wrong (`validation_failed`), a connect link's `return_url` isn't on an allowed domain (`return_url_not_allowed`), an account needs reconnecting (`account_not_connected`), or a network refuses the post as it is (e.g. `text_too_long`, `media_required`, `time_in_past`). `details` lists each problem with the account it is about.
429	`rate_limited`	More than 60 requests in a minute (`rate_limited`).
500	`internal_error`	Something went wrong on our side (`internal_error`). Safe to retry with the same Idempotency-Key.