API Documentation

Complete reference for integrating with the RecurPost social media management platform

Base URL https://social.recurpost.com

Find it in RecurPost: Account settingsAPI key

Getting Started

Start building with your AI agent

Paste this prompt into Claude Code, Cursor, Codex, or any other AI assistant to learn about the RecurPost API and start building.

Help me build tools and automations using the RecurPost API.
Start by reading the developer docs at https://developers.recurpost.com
- especially the Authentication, Request Format and API Endpoints sections.

Then:
1. List the actions I can perform using the RecurPost API.
2. Walk me through authenticating with my email and API key (pass_key)
in my local development environment.

Getting Started

Authentication

Every request is authenticated with your RecurPost account email and your API key. The recommended flow exchanges the key for a short-lived access token once, then sends that token in the Authorization header of every call.

The API key is not your login password. Generate it under Account settings › API key in your RecurPost dashboard. Regenerating the key invalidates the old one and revokes every access token issued with it.

1. Bearer token (recommended)

Call /api/user_login with emailid and pass_key. The response contains a token, its expires_at time (UTC) and expires_in (3600 seconds). Send the token on every other endpoint.

Token rules

Lifetime

One hour from login. expires_at is ISO 8601 in UTC.

Refresh

There is no refresh token. Call /api/user_login again to get a new one. Logging in does not invalidate tokens that are still valid.

Expired

HTTP 401 with "code": "token_expired". Log in again instead of retrying.

Unknown

HTTP 401 with "code": "token_invalid".

Revocation

Regenerating your API key in Account settings revokes all of your tokens at once.

Precedence

When a Bearer header is present, any emailid / pass_key in the body is ignored.

2. Basic header

If you prefer not to manage tokens, send the key on every call as HTTP Basic auth: Authorization: Basic base64(emailid:pass_key). Most HTTP clients build this header for you from a username and password pair.

3. Credentials in the body (legacy)

Existing integrations that send emailid and pass_key (alias zapier_key) inside the request body keep working. New integrations should use a Bearer token or the Basic header so that credentials never travel in the payload.

Failed logins. Repeated wrong keys lock the email address for a short period and answer HTTP 429 with the time to wait. Login and signup calls are also capped at 120 per minute per IP address.

curl -X POST https://social.recurpost.com/api/user_login \
  -H "Content-Type: application/json" \
  -d '{"emailid": "you@example.com", "pass_key": "your_api_key"}'

# {"status":200,"message":"Success","user_info":{...},
#  "token":"3f9c1b7e...","expires_at":"2026-10-22T11:30:00Z","expires_in":3600}

curl -X POST https://social.recurpost.com/api/workspace_list \
  -H "Authorization: Bearer 3f9c1b7e..." \
  -H "Content-Type: application/json" \
  -d '{}'

Basic auth

curl -X POST https://social.recurpost.com/api/workspace_list \
  -u "you@example.com:your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

Getting Started

Request Format

Every endpoint is a POST. Send parameters as a JSON object; application/x-www-form-urlencoded bodies are accepted too, but JSON is required for nested values such as arrays of image URLs or per-network tabs.

MethodPOST

Content-Typeapplication/json

AuthorizationBearer <token> or Basic <base64>, see Authentication

Base URLhttps://social.recurpost.com

Conventions used across endpoints

Ids

Account, library, workspace and content ids are opaque strings handed out by list endpoints. Pass them back exactly as received. A few queue endpoints take plain integer ids; each parameter description says which.

workspace_id

Optional on almost every endpoint. Defaults to your default workspace. Get ids from /api/workspace_list; shared workspaces act on the owner's accounts and libraries.

page, per_page

List endpoints page their results. page starts at 1, per_page defaults to 20 and is capped at 50. Responses include total.

Dates

YYYY-MM-DD for dates and YYYY-MM-DD HH:MM:SS for date-times, interpreted in the workspace owner's timezone unless the parameter says otherwise. See Date/Time Formats.

Success body

Every successful response carries "status": 200 and a message, followed by the endpoint's data fields.

Error body

{"status": 4xx, "error": "message"}, plus a machine readable code on token errors.

Example Request (cURL)

curl -X POST "https://social.recurpost.com/api/library_list" \
  -H "Authorization: Bearer $RECURPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "wS9kLm2Qp1==",
    "page": 1,
    "per_page": 20
  }'

Getting Started

Rate Limits

Calls are counted per RecurPost user. The allowance grows with the number of social accounts on your plan, so larger plans get more room.

Limits

Per minute

5 calls per social account on your plan, at least 60 and at most 600 per minute. Enforced: calls over the limit get HTTP 429.

Per day

2,500 calls per social account, at least 5,000 per day (UTC). Counted but not refused yet; an email warns you at 80% of the daily allowance.

Trial accounts

30 per minute, 2,000 per day.

120 per minute per IP address, before any user is known.

Headers on every response

X-RateLimit-Limitinteger

Calls allowed per minute for your account.

X-RateLimit-Remaininginteger

Calls left in the current minute.

X-RateLimit-Resetinteger

Seconds until the minute window resets.

Retry-Afterinteger

Only on HTTP 429: seconds to wait before retrying.

Need more? Adding social accounts to your plan raises the allowance automatically. For integrations with special needs contact support for a per-account override.

Rate limit reached

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23
Retry-After: 23

{"status": 429, "error": "Rate limit exceeded. Try again in 23 seconds."}

Getting Started

Response Codes

The API uses standard HTTP status codes. The same code is repeated in the JSON body as status.

200

Success

Request completed. The body carries the endpoint's data.

400

Bad Request

Missing or invalid parameters. The error text names the problem.

401

Unauthorized

Wrong email or API key, or an expired / unknown access token (code is token_expired or token_invalid).

403

Forbidden

The account, library or post is not yours, or your plan does not allow the action.

404

Not Found

The id does not exist in the selected workspace.

405

Method Not Allowed

Use POST for all requests.

409

Conflict

The action does not fit the current state, for example retrying a post that has not failed.

415

Unsupported value

A schedule time in the past, or a media URL that is not publicly reachable.

422

Unprocessable

The post content fails a network rule (length, media type, missing required field for that network).

429

Too Many Requests

Rate limit or login lock. Wait for Retry-After seconds.

500

Server Error

Something failed on our side. Retry later; if it persists contact support with the request details.

Legacy endpoints and HTTP 200. Ten documented endpoints predate this API version and are marked legacy below: user_login, social_account_list, connect_social_account_urls, workspace_list, library_list, history_data, add_content_in_library, post_content, generate_content_with_ai and generate_image_with_ai. When you call them with body or Basic credentials, errors arrive as HTTP 200 with the real code in the body's status field, so existing Zapier integrations keep working. Authenticate with a Bearer token and every endpoint, including these, returns real HTTP status codes. HTTP 429 is always sent as a real status.

Reference

Platform Prefixes

Quick reference for platform-specific parameter prefixes.

Facebookfb_

fb_messagefb_post_typefb_first_commentfb_thumb

Instagramin_

in_messagein_post_typein_first_commentin_thumb

Twitter/Xtw_

tw_message

LinkedInln_

ln_messageln_first_commentln_documentln_thumb

Pinterestpi_

pi_messagepi_title

YouTubeyt_

yt_messageyt_titleyt_category

TikToktk_

tk_messagetk_privacy_status

Meta Threadsth_

th_message

Blueskybs_

bs_message

Google Businessgmb_/gbp_

gmb_messagegbp_ctagbp_offer_title

Reference

Date/Time Formats

Reference for date and time formats used in the API.

Parameter	Format	Example
`schedule_date_time`	`YYYY-MM-DD HH:MM:SS`	`2024-06-23 15:30:00`
`content_livedate`	`YYYY-MM-DD`	`2024-06-23`
`content_expiredate`	`YYYY-MM-DD`	`2024-12-31`
`gbp_offer_start_date`	`YYYY-MM-DD HH:MM:SS`	`2024-06-23 09:00:00`
`gbp_offer_end_date`	`YYYY-MM-DD HH:MM:SS`	`2024-06-30 23:59:59`

Reference

Troubleshooting

Solutions for common issues encountered when using the API.

Problem: Images are not appearing when the post is published.

Solution:

Ensure image_url is an array, not a string
Verify URLs are publicly accessible (not behind authentication)
Set host_images_on_recurpost to "true" for reliability

Correct Format

"image_url": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]

Incorrect Format

"image_url": "https://example.com/image.jpg" // Wrong! Must be array

Problem: Getting a 401 Unauthorized error, or every call answers token_invalid.

Solution:

Verify pass_key is the API key from Account settings, NOT your login password
Ensure emailid matches your RecurPost account exactly
Check that your API key hasn't been regenerated
If the body says "code": "token_expired", call /api/user_login again: tokens last one hour
Send the token as Authorization: Bearer <token>; a Bearer header takes precedence over credentials in the body

Problem: Getting 415 error when scheduling posts.

Solution:

Ensure schedule_date_time is in the future
Use correct format: YYYY-MM-DD HH:MM:SS
Example: 2024-12-25 10:00:00

Solution: Google Drive videos require special handling. See the detailed guide:

Google Drive Video Import Guide

Problem: Getting 400 Validation Error.

Solution:

Check all required parameters are included
Verify parameter names are spelled correctly
Ensure JSON is valid (use a JSON validator)
Check that id is valid (library ID or social account ID)

API Documentation

Start building with your AI agent

Authentication

1. Bearer token (recommended)

Token rules

2. Basic header

3. Credentials in the body (legacy)

Request Format

Conventions used across endpoints

Rate Limits

Limits

Headers on every response

Response Codes

Platform Prefixes

Date/Time Formats

Troubleshooting

Images not appearing in posts

Authentication fails (401 Error)

Scheduled post error (415)

Using videos from Google Drive

Validation error (400)