API Reference/Posts/Create a post

Create a post

POSThttps://api.postpress.ai/v1/posts

Publish a post.

Authorization

X-API-KEYstringrequired
API key from your postpress dashboard. Sent as a request header.

Request body

Submit the request as multipart/form-data so binary attachments can be uploaded alongside text fields. Object/array fields (such as mentions) should be sent as JSON-encoded strings.

account_idstringrequired
The id of the linked account to publish from.
textstringrequired
The post text. LinkedIn: insert a mention by placing the index of the matching `mentions` entry between double braces, e.g. `Hey {{0}}, check this out!`. Instagram: mention a user with `@username`.
attachmentsarray of files (binary)
Media files to attach. On LinkedIn, image file resolution is limited to 6012x6012 px max.
video_thumbnailfile (binary)
Optional custom thumbnail used when a video is attached.
repoststring
The id of an existing LinkedIn post to publish as a repost. For a simple repost with no commentary, set `text` to an empty string.
include_job_postingstring
LinkedIn only. The id of a job posting that should be rendered as a preview card.
mentionsarray of objects
LinkedIn only. The list of users referenced from the `text` via `{{index}}` placeholders.
mentions object
namestringrequired
The name of the user as it will be displayed in your post.
profile_idstringrequired
The provider id of the user. Begins with ACo/ADo for individuals and is a series of digits for companies.
is_companyboolean
Set to true when mentioning a company page.
external_linkstring
LinkedIn only. An external URL to render as a preview card. The URL must also appear in `text`; if it doesn't, it is appended to the end. Must match `^https?://`.
as_organizationstring
LinkedIn only. The id of an organization you administer, to publish the post on its behalf.
locationstring
Instagram only. The location to tag in the post.

Response 201 Created

Returned when the post has been published successfully.

objectstringPostCreatedrequired
post_idstringrequired
The id of the published post, when available from the provider.

Example request

curl --request POST \
  --url https://api.postpress.ai/api/v1/posts \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data' \
  --form 'account_id=acc_linkedin_01HXYZ4QK3WJ8FN3M6QH7TZ8GR' \
  --form 'text=Excited to share what we shipped this week.'

Example response

{
  "object": "PostCreated",
  "post_id": "urn:li:share:7332661864792854528"
}

Errors

Every error response follows the same envelope:

titlestringrequired
Short error title.
detailstringoptional
Human-readable explanation.
instancestringoptional
Request identifier for support.
typestringrequired
Error type identifier.
statusnumberrequired
HTTP status code.
401 Unauthorized13 types

Credentials are missing, expired, or otherwise invalid.

  • errors/missing_credentials - Some credentials are necessary to perform the request.
  • errors/multiple_sessions - LinkedIn limits multiple sessions on certain Recruiter accounts. Use the cookie connection method.
  • errors/wrong_account - The provided credentials do not match the correct account.
  • errors/invalid_credentials - The provided credentials are invalid.
  • errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
  • errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully. Retry.
  • errors/checkpoint_error - The checkpoint does not appear to be resolvable.
  • errors/expired_credentials - Credentials have expired. Reconnect the account.
  • errors/expired_link - This link has expired. Generate a new one.
  • errors/insufficient_privileges - This resource is out of your API-key scopes.
  • errors/disconnected_account - The account is disconnected from the provider service.
  • errors/disconnected_feature - The service you're trying to reach is disconnected.
  • errors/invalid_credentials_but_valid_account_imap - IMAP/SMTP credentials are invalid but the account is otherwise valid.
403 Forbidden9 types

Authenticated but the account is restricted or the action is not allowed.

  • errors/insufficient_permissions - Valid authentication but insufficient permissions to perform the request.
  • errors/account_restricted - The account has been restricted by the provider.
  • errors/account_mismatch - This action cannot be done with your account.
  • errors/unknown_authentication_context - An additional step seems necessary to complete login.
  • errors/session_mismatch - Token user id does not match client session id.
  • errors/feature_not_subscribed - The requested feature has not been subscribed or authenticated properly.
  • errors/subscription_required - A subscription is required to use this feature.
  • errors/resource_access_restricted - You don't have access to this resource.
  • errors/action_required - An additional step is required.
500 Internal Server Error3 types

Something went wrong on our side or with the upstream provider.

  • errors/unexpected_error - Something went wrong.
  • errors/provider_error - The provider is experiencing operational problems. Retry later.
  • errors/authentication_intent_error - The current authentication intent was killed after failure.
503 Service Unavailable5 types

postpress is temporarily unable to handle the request.

  • errors/no_client_session - No client session is currently running.
  • errors/no_channel - No channel to client session.
  • errors/no_handler - Handler missing for that request.
  • errors/network_down - Network is down on the server side. Retry shortly.
  • errors/service_unavailable - Service temporarily unavailable. Retry later.
504 Gateway Timeout1 types

The upstream provider did not respond in time.

  • errors/request_timeout - Request timed out. Retry, and contact support if it persists.
Updated May 2026