Publish once.
Ship everywhere.

Authentication and scope

Create an API key in Settings → API keys. The complete key is copied and shown once. Store it in a server-side secret manager.

Authorization: Bearer wrp_live_your_key
Content-Type: application/json

Keys are stored as one-way hashes, can be deleted from Settings, and are never accepted for a profile belonging to another Werepost account. Every API-key request is scoped with a profile_id. A key owned by an account can address that account's profiles, but it cannot cross account ownership.

Connection-management endpoints use a signed-in Werepost user access token, not an API key. For a normal server integration, connect destinations in the Werepost app and use the API key only for post operations.

Quickstart

1. Sign in to Werepost and create or select a profile.
2. Connect every destination from the profile's Connections page. Finish page or channel selection where required.
3. Create an API key in Settings and save the one-time value.
4. Host the video at a fetchable public HTTPS CDN URL.
5. Send a create request with a unique Idempotency-Key.

curl https://werepost.ai/api/v1/posts \
  --request POST \
  --header "Authorization: Bearer $WEREPOST_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: product-launch-2026-08-21" \
  --data '{
    "profile_id": "4a40c92d-68af-4f10-b1cc-881591b575fd",
    "title": "Product launch",
    "caption": "A first look at what we built.",
    "media_url": "https://cdn.example.com/video/launch.mp4",
    "platforms": ["tiktok", "instagram", "youtube"]
  }'

A new request returns 201. A replay that resolves to an existing post returns 200 with "idempotent": true.

Media and CDN flow

API clients supply media by URL. Werepost validates the URL, prepares the remote media for publishing, and passes the resulting media reference into the selected platform jobs.

There is no public multipart upload endpoint in /api/v1. The Werepost web app uploads files to its private media bucket and uses an internal storage://scheduled-videos/… reference. That form is reserved for app-managed uploads; external API clients should use a public HTTPS CDN URL.

Deleting a post removes app-managed private media associated with that record. Werepost does not delete an object from your public CDN.

Create a post

Immediate publishing

Omit scheduled_at. Werepost places the job shortly ahead so the remote media can be prepared safely. “Immediate” is asynchronous: use the returned post ID to check delivery.

Scheduled publishing

{
  "profile_id": "4a40c92d-68af-4f10-b1cc-881591b575fd",
  "caption": "Publishing Tuesday at 16:30 Paris time.",
  "media_url": "https://cdn.example.com/video/tuesday.mp4",
  "platforms": ["facebook", "linkedin"],
  "scheduled_at": "2026-08-25T14:30:00Z"
}

Send a timezone-aware timestamp. UTC with a trailing Z is recommended. A timestamp materially in the past returns 400 invalid_schedule.

Supported platform keys

tiktok, instagram, facebook, youtube, x, linkedin, pinterest, reddit, bluesky, threads, googlebusiness, and discord. Use GET /api/v1/platforms as the live source of truth.

Platform options

Keys under platform_options match the Werepost platform key. Omitted booleans default to false unless stated otherwise.

{
  "platforms": ["pinterest", "reddit", "discord"],
  "platform_options": {
    "pinterest": { "board_name": "Product launches", "alt_text": "Product demo" },
    "reddit": { "subreddit": "r/SideProject", "title": "What we shipped" },
    "discord": { "channel_id": "123456789012345678" }
  }
}

Platform policies can impose additional requirements that depend on the connected account or content. Those rejections are returned as safe Werepost errors or appear in the post's error field after refresh.

Idempotency

Every create request requires an Idempotency-Key header containing 8–128 letters, digits, dots, underscores, colons, or dashes.

• Generate one key for one intended post and reuse it for every retry of that same intent.
• The key is combined with profile_id, so the same literal key in two different profiles does not identify the same post.
• A confirmed new post returns 201 and idempotent: false.
• A replay that already has a publishing job returns 200 and the existing post with idempotent: true.
• Do not reuse a key with different content. Werepost compares a stable request fingerprint and returns 409 idempotency_conflict when the same key is used for a different request.

If a request times out or the connection drops, retry the exact request with the same key. For 429, 502, or 503, use exponential backoff and preserve the key.

For clients that cannot set headers, idempotency_key in the JSON body is accepted as a compatibility fallback. The header is the production recommendation.

Status and refresh

Without a query parameter, this endpoint returns the last state stored by Werepost. Add ?refresh=true to synchronise the publishing job before responding.

curl "https://werepost.ai/api/v1/posts/4cf807c9-5e93-4c98-9077-586b5ce0e20e?refresh=true" \
  --header "Authorization: Bearer $WEREPOST_API_KEY"

provider_status gives the detailed state when available, including UPLOADING, SCHEDULED, PROCESSING, RETRYING, REVIEW, POSTED, ERROR, and DELETED.

Per-platform deliveries

Every post response also includes deliveries, an array with one entry per destination. This is the best field for partial success: the overall post can finish while a specific platform reports its own result.

{
  "platform": "youtube",
  "status": "delivered",
  "external_id": "video_123",
  "external_url": "https://www.youtube.com/watch?v=video_123",
  "error": null,
  "delivered_at": "2026-08-25T14:31:08.000Z"
}

Delivery status is one of pending, uploading, delivered, or failed. external_id and external_url are present only when the destination returns them. Errors and URLs are sanitised before Werepost exposes them.

Lists posts in descending scheduled order. API keys must include profile_id. limit defaults to 100 and is clamped from 1 to 200.

Retry and delete

Retries an existing failed publishing job, immediately refreshes it, and returns { "data": post }. If the original create failed before a publishing job existed, Werepost returns 409 resubmit_required. Resend the original POST /posts request with the same Idempotency-Key.

Attempts to cancel the job, removes app-managed private media if applicable, and deletes the Werepost post record. It returns:

{
  "deleted": true,
  "id": "4cf807c9-5e93-4c98-9077-586b5ce0e20e"
}

Connection flow

Connection routes are used by the Werepost web application and require a signed-in user access token. They reject wrp_live_… API keys. This prevents a leaked publishing key from authorising or disconnecting social accounts.

1. Provision the owned profile with POST /profiles/{profile_id}/provision.
2. Request a direct platform URL with GET /connect/{platform}?profile_id={uuid}.
3. Navigate the browser to the returned url. It is a fresh provider authorisation URL; do not store it.
4. After the browser returns to Werepost, call GET /connections?profile_id={uuid}.
5. If the connection says needs_channel_selection: true, present its channels and submit one selection.

choose_account defaults to true so providers ask which account to use where supported. The response is { "url": "https://…", "platform": "tiktok" }.

Returns account display data, connection status, and available destinations. Valid status values are connected, action_required, and disconnected.

Disconnects the platform for this profile. It does not delete existing posts from the destination.

Channel selection

Facebook, YouTube, LinkedIn, and Google Business may return pages, channels, organisations, or locations that require a selection. Use the exact channel id returned in connections[].channels.

{
  "profile_id": "4a40c92d-68af-4f10-b1cc-881591b575fd",
  "platform": "youtube",
  "channel_id": "UC123456789"
}

Werepost verifies that the channel belongs to the profile's connection and refreshes the available channel list once if necessary. Publishing returns 409 channel_selection_required until setup is complete.

Endpoint reference

The authoritative request and response schemas are available as OpenAPI 3.1 JSON.

Errors

Every error is JSON. The request_id also appears in the X-Request-Id response header.

{
  "error": "platform_not_connected",
  "message": "Connect every selected platform before publishing.",
  "details": {
    "missing": ["tiktok"],
    "needs_channel": []
  },
  "request_id": "b4805362-5580-4eb0-b4e3-d95b30235b2b"
}

For status codes below 500, message describes the problem. For 5xx errors it is deliberately generic; record the request ID. Structured details may identify missing platforms, destinations awaiting channel selection, or safe validation issues.

Production checklist

• Keep the API key in a server-side secret manager and rotate it after any suspected exposure.
• Persist the Werepost profile_id and post id; never infer profile ownership client-side.
• Generate and persist an idempotency key before the first create attempt.
• Use a durable HTTPS CDN URL and keep it available until the post is accepted.
• Supply required Pinterest, Reddit, and Discord options when those destinations are selected.
• Use refresh=true with backoff until a post reaches delivered or failed.
• Handle 409 resubmit_required by replaying the original create request with the original idempotency key.
• Log X-Request-Id with your request metadata, but never log Bearer credentials or sensitive authorisation URLs.
• Expect platform-specific rejection and review. A successful API response means the job was accepted, not that every destination has published it.

Questions or a reproducible failure? Email info@sofuto.uk with the request ID, endpoint, timestamp, and post ID. Do not include your API key.