Profiles
One profile per end customer, and the connect URL they sign in through.
One profile per end customer, when you are building a platform on yeetpost.
Create a profile
POST/profiles
Creates one end customer's profile. Connect accounts into it with the console, then post to them with profileId.
Rate limit: 60 requests per minute per API key.
curl -X POST "https://api.yeetpost.com/api/v2/profiles" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "name": "Acme Coffee", "externalId": "cus_4821"}'{ "profile": { "id": "b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b", "name": "Acme Coffee", "externalId": "cus_4821", "createdAt": "2026-08-29T09:24:11.412Z" }}request body (application/json)
What you call this end customer.
Your own id for the same end customer. Unique across your account: a second profile with the same one is refused with profile_external_id_conflict.
response 200
The profile.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
The profile's id, which you send as profileId when posting and connecting.
What you call this end customer. Shown in the console, never sent to a platform.
Your own id for the same end customer, unique across your account. Null when you did not give one.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
errors
A body without a name, a name outside 1 to 100 characters, or an externalId outside 1 to 200 characters.
Missing or invalid API key.
You already have 1000 profiles, which is the most an account can have at once (limit_exceeded; a deleted profile does not count), or the key is scoped to one profile and cannot create them (forbidden).
Another profile of yours already carries this externalId.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
List your profiles
GET/profiles
Lists your profiles, newest first. A key scoped to a profile lists that one profile and nothing else. The MCP tool list_profiles answers the same.
Rate limit: 60 requests per minute per API key.
curl "https://api.yeetpost.com/api/v2/profiles" \ -H "x-api-key: $YEETPOST_API_KEY"{ "profiles": [ { "id": "b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b", "name": "Acme Coffee", "externalId": "cus_4821", "createdAt": "2026-08-29T09:24:11.412Z" } ], "limit": 25, "offset": 0}query parameters
How many profiles to return.
How many profiles to skip, for paging.
response 200
Your profiles.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
The profile's id, which you send as profileId when posting and connecting.
What you call this end customer. Shown in the console, never sent to a platform.
Your own id for the same end customer, unique across your account. Null when you did not give one.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
errors
A limit outside 1 to 100, or a negative offset.
Missing or invalid API key.
This API key is scoped to one profile, and the endpoint is outside that scope. Profiles are managed with an unscoped key; a scoped key may only read its own profile and connect accounts into it.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Get one profile
GET/profiles/{profileId}
Reads one profile of yours.
Rate limit: 60 requests per minute per API key.
curl "https://api.yeetpost.com/api/v2/profiles/b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b" \ -H "x-api-key: $YEETPOST_API_KEY"{ "profile": { "id": "b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b", "name": "Acme Coffee", "externalId": "cus_4821", "createdAt": "2026-08-29T09:24:11.412Z" }}path parameters
The profile's id.
response 200
The profile.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
The profile's id, which you send as profileId when posting and connecting.
What you call this end customer. Shown in the console, never sent to a platform.
Your own id for the same end customer, unique across your account. Null when you did not give one.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
errors
A malformed profile id, a name outside 1 to 100 characters, an externalId outside 1 to 200 characters, or a body that names neither.
Missing or invalid API key.
This API key is scoped to one profile, and the endpoint is outside that scope. Profiles are managed with an unscoped key; a scoped key may only read its own profile and connect accounts into it.
No profile of yours has that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Rename a profile
PATCH/profiles/{profileId}
Changes a profile's name, its external id, or both. Its connections are untouched.
Rate limit: 60 requests per minute per API key.
curl -X PATCH "https://api.yeetpost.com/api/v2/profiles/b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "name": "Acme Coffee Roasters"}'{ "profile": { "id": "b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b", "name": "Acme Coffee", "externalId": "cus_4821", "createdAt": "2026-08-29T09:24:11.412Z" }}path parameters
The profile's id.
request body (application/json)
Null takes the external id off the profile.
response 200
The profile.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
The profile's id, which you send as profileId when posting and connecting.
What you call this end customer. Shown in the console, never sent to a platform.
Your own id for the same end customer, unique across your account. Null when you did not give one.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
errors
A malformed profile id, a name outside 1 to 100 characters, an externalId outside 1 to 200 characters, or a body that names neither.
Missing or invalid API key.
This API key is scoped to one profile, and the endpoint is outside that scope. Profiles are managed with an unscoped key; a scoped key may only read its own profile and connect accounts into it.
No profile of yours has that id.
Another profile of yours already carries this externalId.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Delete a profile
DELETE/profiles/{profileId}
Deletes the profile and disconnects every account inside it: the credentials are deleted, the posts that already went out stay readable, and anything still waiting to be sent is cancelled. Your bill drops to the connections you have left.
Rate limit: 60 requests per minute per API key.
curl -X DELETE "https://api.yeetpost.com/api/v2/profiles/b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b" \ -H "x-api-key: $YEETPOST_API_KEY"{ "id": "b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b", "deleted": true, "removedConnections": 2}path parameters
The profile's id.
response 200
The profile is gone.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
true
How many connections went with the profile.
errors
A malformed profile id, a name outside 1 to 100 characters, an externalId outside 1 to 200 characters, or a body that names neither.
Missing or invalid API key.
This API key is scoped to one profile, and the endpoint is outside that scope. Profiles are managed with an unscoped key; a scoped key may only read its own profile and connect accounts into it.
No profile of yours has that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Get a connect URL for a profile
POST/profiles/{profileId}/connect
Answers with a hosted page you send your end customer to. They connect one of their own accounts into this profile there and come back to your redirectUrl with the connection on the query.
The link works once and lasts fifteen minutes. It carries the whole authorization: nobody signs in to yeetpost, and the page never shows your key, your email or anything about your other customers.
When an account was connected, the customer lands on your redirectUrl with connectSessionId, connectionId, profileId, slug and platform added to its query. When they cancelled or the platform refused, they land with connectSessionId and error (cancelled or connect_failed) instead, and no connection was made. Any query string your redirectUrl already carries is kept; these parameters are added to it.
Leave redirectUrl out when there is no site of yours to send them back to: the customer finishes on a yeetpost page that says they are connected and can close the tab, and the link then lasts seven days. Read how it ended with getConnectSession.
Pass connectionId to reconnect a connection that stopped working instead of adding a new one. The connection keeps its id and slug if the customer signs in to the same account; a different account becomes a new connection. The profile and platform are taken from the connection, so platform may be left out or must match it.
A test key opens a session that offers the sandbox and nothing else, which is how you run the whole flow in CI without connecting anybody's account.
A key scoped to a profile may only open sessions for that one; another profile answers 403 forbidden. When the key carries a redirect allowlist, redirectUrl must be on one of its origins. The MCP tool create_connect_link does the same.
Rate limit: 60 requests per minute per API key.
curl -X POST "https://api.yeetpost.com/api/v2/profiles/b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b/connect" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "platform": "linkedin", "redirectUrl": "https://acme.example.com/settings/social"}'{ "url": "https://yeetpost.com/connect/8Qm2rXk9vT1sB4nE6yPzL0aJdHcWfUgR", "expiresAt": "2026-08-29T09:39:11.412Z", "connectSessionId": "7f3c9a10-2b4d-4e88-9f01-3a5b7c9d1e2f"}path parameters
The profile the new connection goes into.
request body (application/json)
The platform to connect. Leave it out and the end customer picks one on the page. A test key may only name sandbox. Reddit needs the install's Reddit app, Facebook, Instagram and Threads need its Meta app, and Google Business Profile needs its Google app and Google's approval: where one is not configured, the hosted page leaves those platforms out and naming one is refused.
linkedin | x | bluesky | mastodon | discord | telegram | sandbox | reddit | facebook | instagram | threads | google_business
Where the end customer goes when the flow ends, either way. Must be an https URL on a public host with no fragment; plain http is accepted for localhost only. It is bound to the session here and used exactly as stored, so nothing in the hosted page's own query can change where they land. When the API key carries a redirect allowlist, the URL's scheme, host and port must match one of its origins exactly; a key with no allowlist accepts any public https URL. Leave it out and the customer finishes on a yeetpost page that says they are connected and can close the tab; the link then lasts seven days instead of fifteen minutes.
Draws the hosted page with no yeetpost header or footer, for a popup with your own branding around it.
Reconnect this connection instead of adding a new one. It must be a connection of the profile in the path. The connection keeps its id and slug if the customer signs in to the same account; a different account becomes a new connection. The platform is taken from the connection.
response 200
The hosted url, its expiry and the session id.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
The page to send your end customer to. It carries a single use token and this is the only time it is shown: only its hash is stored and it cannot be read back.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
Comes back on the redirect and on the connection.created event, and is what GET /connect-sessions/{connectSessionId} answers for.
errors
A malformed profile id, a redirectUrl that is not an https URL on a public host, a redirectUrl with a fragment, a redirectUrl outside the key's redirect allowlist, a platform yeetpost cannot connect, a platform a test key cannot reach, or a connectionId that is the account's own rather than a profile's, belongs to another profile, or is on a different platform than platform.
Missing or invalid API key.
This API key is scoped to one profile, and the endpoint is outside that scope. Profiles are managed with an unscoped key; a scoped key may only read its own profile and connect accounts into it.
No profile of yours has that id, or no connection you can reach has that connectionId.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Read a connect session
GET/connect-sessions/{connectSessionId}
How a connect link ended, for when you would rather poll than read the query your customer came back on. Both say the same thing.
Rate limit: 60 requests per minute per API key.
curl "https://api.yeetpost.com/api/v2/connect-sessions/7f3c9a10-2b4d-4e88-9f01-3a5b7c9d1e2f" \ -H "x-api-key: $YEETPOST_API_KEY"{ "connectSession": { "id": "7f3c9a10-2b4d-4e88-9f01-3a5b7c9d1e2f", "profileId": "b2d1f0a3-5c6e-4f70-8a9b-0c1d2e3f4a5b", "platform": null, "status": "connected", "connectionId": "c4e2a1b6-8d3f-4a71-b0c9-5e6f7a8b9c0d", "error": null, "redirectUrl": "https://acme.example.com/settings/social", "headless": false, "expiresAt": "2026-08-29T09:39:11.412Z", "createdAt": "2026-08-29T09:24:11.412Z" }}path parameters
The id POST /profiles/{profileId}/connect answered with.
response 200
The connect session.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
The platform the link was opened for, null when the end customer picks one on the page.
linkedin | x | bluesky | mastodon | discord | telegram | sandbox | reddit | facebook | instagram | threads | google_business | null
pending while the customer still has the link open, connected once an account came in, failed when they cancelled or the platform refused, expired when the fifteen minutes ran out with nothing happening.
pending | connected | failed | expired
The connection that was made, null until one is.
Why the customer came back without a connection: cancelled when they backed out, connect_failed when the platform refused. Null otherwise.
cancelled | connect_failed | null
Null when the link was made without one.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
An ISO 8601 timestamp in UTC, in the same format as the timestamps you send in: 2026-08-26T09:24:11.412Z.
errors
A malformed connect session id.
Missing or invalid API key.
No connect session of yours has that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.