Home DocsREST API Reference

Developer reference

REST API Reference

Schedule and publish social posts, manage connections, media, and webhooks with a standard Bearer-token API. One key, cursor pagination, a single error envelope.

https://sharetopus.com/api/v1interactive explorer openapi.json

The OpenAPI 3.1 document at /api/v1/openapi.json is generated from the same zod schemas that validate requests at runtime; use it for codegen and the interactive explorer at /docs/api to try calls.

Authentication

Every endpoint requires a Bearer API key. Keys are scoped to your account and require an active subscription.

1
Create a key.
In the web app, open /integrations and click Create REST API Key. The key starts with stp_rest_ and is shown once; store it like a password.
2
Send it on every request.
Authorization: Bearer stp_rest_... . Keys are validated against a SHA-256 hash, checked for expiry, and require an active subscription.
3
Handle 401 as terminal.
A 401 unauthorized means the key is missing, malformed, expired, or the subscription lapsed. Rotating the key or fixing billing are the only remedies; retrying does not help.

Quickstart · cURL

# Every request carries the API key as a Bearer token
curl "https://sharetopus.com/api/v1/posts" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Response · 401

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  },
  "request_id": "8f0a3c52-7c1e-4b8e-9f21-d4a0c0b6e7aa"
}

Every response carries an x-request-id header (echoed as request_id in error bodies). Include it when contacting support.

Pagination

List endpoints use cursor pagination on the resource creation date, newest first. The cursor is opaque: always pass back next_cursor exactly as received.

1
Request a page.
limit accepts 1 to 100 and defaults to 20 on every list endpoint.
2
Follow next_cursor.
The response envelope is { data, next_cursor }. A null next_cursor means the last page. Pass the value back as ?cursor= to fetch the next page.

Example · Two pages

# First page
curl "https://sharetopus.com/api/v1/posts?limit=20" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

# Next page: pass next_cursor from the previous response
curl "https://sharetopus.com/api/v1/posts?limit=20&cursor=2026-07-01T09:30:00.000Z" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Response · Envelope

{
  "data": [ { "...": "resource objects, newest first" } ],
  "next_cursor": "2026-07-01T09:30:00.000Z"
}

Error codes

Every error response uses one envelope: { error: { code, message, details? }, request_id }. details appears only on validation errors and rate limits.

Status	Code	Meaning
400	validation_error	The body or query failed schema validation, or the JSON is malformed. details carries the field-level issues.
401	unauthorized	Missing, malformed, or expired API key, or no active subscription.
403	forbidden	Key lacks the required scope, quota exhausted, or file access denied.
404	not_found	The resource does not exist or is not owned by your account. Unowned resources return 404, never 403.
429	rate_limited	Per-key rate limit exceeded. See Rate limits.
500	internal_error	Server-side failure. Retry with backoff; include request_id when reporting.

Rate limits

Limits are enforced per API key and per action (for example rest.posts.create). A 429 carries retry_after_seconds in the error details when the window is known.

Response · 429

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "details": { "retry_after_seconds": 42 }
  },
  "request_id": "8f0a3c52-7c1e-4b8e-9f21-d4a0c0b6e7aa"
}

Posts

Create, list, inspect, reschedule, and cancel posts. Omitting scheduled_at publishes immediately; providing it schedules for that time.

POST

Create a post

/api/v1/posts

Schedules a post (scheduled_at in the future) or publishes immediately (scheduled_at omitted). Validation is platform-aware: unsupported media types and missing Pinterest boards are rejected with 400 validation_error.

Request Body

Parameter	Type	Required	Description
social_account_id	string (uuid)	Required	Connected account to post from (see Connections).
platform	string	Required	linkedin, tiktok, pinterest, instagram, youtube, x, or facebook. Must match the account.
post_type	string	Required	text, image, or video. Media-type support is validated per platform (for example youtube accepts video only).
description	string \| null	Required	Post body text, max 10000 characters. The key is required; the value may be null.
title	string	Optional	Max 500 characters, where the platform supports one.
media_storage_path	string	Optional	Required for image and video posts. The storage_path returned by the Media endpoints; format {principal_id}/filename.
scheduled_at	string	Optional	Future ISO 8601 timestamp with offset. Omit to publish immediately.
idempotency_key	string	Optional	1 to 200 characters. Client-supplied key to dedupe retries.
batch_id	string	Optional	Request-level grouping id.
pinterest_board_id	string	Optional	Required when platform is pinterest.
pinterest_board_name	string	Optional	Board name, informational.
pinterest_link	string (url)	Optional	Outbound link for the pin, max 2048 characters.

Response Fields (PostDTO)

Parameter	Type	Required	Description
id	string (uuid)	Required	Post id.
status	string	Required	scheduled, queued, processing, posted, failed, or cancelled.
platform	string	Required	linkedin, tiktok, pinterest, instagram, youtube, x, or facebook.
post_type	string	Required	text, image, or video.
title	string \| null	Required	Title, when set.
description	string \| null	Required	Body text, when set.
scheduled_at	string	Required	Publish time, ISO 8601.
posted_at	string \| null	Required	Set once the post is published.
social_account_id	string (uuid)	Required	Account the post targets.
media_storage_path	string	Required	Storage path of the attached media; empty for text posts.
batch_id	string \| null	Required	Batch the post belongs to, when created in one.
created_at	string	Required	Record creation time, ISO 8601.

Example Request

curl -X POST "https://sharetopus.com/api/v1/posts" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "social_account_id": "5b1f0c4e-3d2a-4f6b-8c9d-0e1f2a3b4c5d",
    "platform": "tiktok",
    "post_type": "video",
    "description": "Launch day.",
    "media_storage_path": "user_2f6a1c0e.../launch.mp4",
    "scheduled_at": "2026-07-12T16:00:00.000Z"
  }'

Response · 200

{
  "id": "c9d8e7f6-a5b4-4c3d-2e1f-0a9b8c7d6e5f",
  "status": "scheduled",
  "platform": "tiktok",
  "post_type": "video",
  "title": null,
  "description": "Launch day.",
  "scheduled_at": "2026-07-12T16:00:00.000Z",
  "posted_at": null,
  "social_account_id": "5b1f0c4e-3d2a-4f6b-8c9d-0e1f2a3b4c5d",
  "media_storage_path": "user_2f6a1c0e.../launch.mp4",
  "batch_id": null,
  "created_at": "2026-07-04T18:00:00.000Z"
}

GET

List posts

/api/v1/posts

Cursor-paginated list, newest first.

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	scheduled, queued, processing, posted, failed, or cancelled.
platform	string	Optional	Filter by posting platform.
batch_id	string	Optional	Filter by batch.
limit	number	Optional	1 to 100. Default 20.
cursor	string	Optional	next_cursor from the previous page.

Example Request

curl "https://sharetopus.com/api/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

POST

Bulk schedule posts

/api/v1/posts/bulk

Schedules 1 to 30 posts in one request; every item takes the same fields as Create a post. All posts share one server-generated batch_id, and each gets the idempotency key batch_id:index unless one is provided. Partial success is possible: rejected items are listed, inserted ones are returned.

Request Body

Parameter	Type	Required	Description
posts	object[]	Required	1 to 30 items, each with the Create a post body fields.

Response Fields

Parameter	Type	Required	Description
success	boolean	Required	True when the batch was processed.
batch_id	string (uuid)	Required	Shared batch id for every post in the call.
total	number	Required	Items received.
inserted	number	Required	Posts stored.
duplicates	number	Required	Items skipped by idempotency key.
rejected	object[]	Required	Items that failed validation, with reasons.
posts	PostDTO[]	Required	The inserted posts.

Example Request

curl -X POST "https://sharetopus.com/api/v1/posts/bulk" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      { "social_account_id": "5b1f0c4e-...", "platform": "x", "post_type": "text", "description": "Thread 1/3", "scheduled_at": "2026-07-12T16:00:00.000Z" },
      { "social_account_id": "5b1f0c4e-...", "platform": "x", "post_type": "text", "description": "Thread 2/3", "scheduled_at": "2026-07-12T16:05:00.000Z" }
    ]
  }'

GET

Get a post

/api/v1/posts/{id}

Returns one post by id. Posts owned by another account return 404.

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Required	Post id.

Example Request

curl "https://sharetopus.com/api/v1/posts/c9d8e7f6-a5b4-4c3d-2e1f-0a9b8c7d6e5f" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

PATCH

Reschedule a post

/api/v1/posts/{id}

Moves a pending post to a new future time. Cancelled posts are automatically resumed by the move. Returns the updated PostDTO.

Request Body

Parameter	Type	Required	Description
scheduled_at	string	Required	Future ISO 8601 timestamp with offset.

Example Request

curl -X PATCH "https://sharetopus.com/api/v1/posts/c9d8e7f6-a5b4-4c3d-2e1f-0a9b8c7d6e5f" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-07-13T09:00:00.000Z" }'

DELETE

Cancel or delete a post

/api/v1/posts/{id}

Default is a soft cancel: the post keeps its row and media, status becomes cancelled. hard=true permanently deletes the post and cleans up its media.

Query Parameters

Parameter	Type	Required	Description
hard	boolean	Optional	true for permanent deletion. Default false (cancel).

Response Fields

Parameter	Type	Required	Description
id	string (uuid)	Required	The post acted on.
action	string	Required	cancelled or deleted.
details	object \| null	Required	Batch-operation details, when available.

hard=true is not reversible and removes stored media that no other post references.

Example Request

curl -X DELETE "https://sharetopus.com/api/v1/posts/c9d8e7f6-a5b4-4c3d-2e1f-0a9b8c7d6e5f?hard=true" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

GET

Get post analytics

/api/v1/posts/{id}/analytics

Returns the metric rows recorded for a published post. 404 when the post does not exist or has no published content yet.

Response Fields

Parameter	Type	Required	Description
post_id	string (uuid)	Required	The post.
content_id	string	Required	Platform-side content identifier.
metrics	object[]	Required	Metric rows: metric_date, views, likes, comments, shares, subscribers.

Example Request

curl "https://sharetopus.com/api/v1/posts/c9d8e7f6-a5b4-4c3d-2e1f-0a9b8c7d6e5f/analytics" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Connections

Connected social accounts. OAuth flows are browser-based: the API returns an authorization URL, the user finishes in the browser, and the account appears in the list. Platform tokens are never returned.

GET

List connections

/api/v1/connections

Cursor-paginated list of connected accounts. By default only available accounts are returned; include_unavailable=true adds accounts whose platform token expired (candidates for reauth).

Query Parameters

Parameter	Type	Required	Description
platform	string	Optional	Any of linkedin, tiktok, pinterest, instagram, facebook, threads, youtube, x.
include_unavailable	boolean	Optional	true to include expired accounts. Default false.
limit	number	Optional	1 to 100. Default 20.
cursor	string	Optional	next_cursor from the previous page.

Response Fields (ConnectionDTO)

Parameter	Type	Required	Description
id	string (uuid)	Required	Account id, used as social_account_id when posting.
platform	string	Required	linkedin, tiktok, pinterest, instagram, facebook, threads, youtube, or x.
account_identifier	string	Required	Platform-side account identifier.
display_name	string \| null	Required	Profile display name.
username	string \| null	Required	Profile handle.
avatar_url	string \| null	Required	Profile image URL.
is_verified	boolean \| null	Required	Platform verification badge, when known.
follower_count	number \| null	Required	Follower count at last sync.
is_available	boolean	Required	False when the platform token expired; use reauth.
token_expires_at	string \| null	Required	Platform token expiry, when the platform reports one.
created_at	string	Required	When the account was connected.

Example Request

curl "https://sharetopus.com/api/v1/connections?include_unavailable=true" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

POST

Initiate an OAuth connection

/api/v1/connections/initiate

Starts an OAuth flow for a new account. Open connect_url in a browser; after the user authorizes, the provider redirects to the Sharetopus callback and the account becomes visible in List connections. The state expires after 15 minutes.

Request Body

Parameter	Type	Required	Description
platform	string	Required	linkedin, tiktok, pinterest, instagram, youtube, x, or facebook.
redirect_url	string (url)	Optional	Custom OAuth redirect URI. Defaults to the Sharetopus callback.

Response Fields

Parameter	Type	Required	Description
connect_url	string	Required	Authorization URL to open in a browser.
state	string	Required	OAuth state token bound to this attempt.
expires_at	string	Required	15 minutes after creation.
connection_id	string (uuid)	Required	Id of the pending connection row.

Example Request

curl -X POST "https://sharetopus.com/api/v1/connections/initiate" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "youtube" }'

GET

Get a connection

/api/v1/connections/{id}

Returns one connected account by id. Accounts owned by another principal return 404.

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Required	Connection id.

Example Request

curl "https://sharetopus.com/api/v1/connections/5b1f0c4e-3d2a-4f6b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

POST

Reauthorize a connection

/api/v1/connections/{id}/reauth

For an account whose platform token expired (is_available false). Returns a fresh authorization URL to open in a browser, plus the current account snapshot.

Response Fields

Parameter	Type	Required	Description
reauth_url	string	Required	Authorization URL to open in a browser.
account	ConnectionDTO	Required	The account being reauthorized.

Example Request

curl -X POST "https://sharetopus.com/api/v1/connections/5b1f0c4e-3d2a-4f6b-8c9d-0e1f2a3b4c5d/reauth" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

GET

List Pinterest boards

/api/v1/connections/{id}/boards

Boards of a connected Pinterest account, for the pinterest_board_id field when posting. 400 when the account is not Pinterest; 401 with a reauth_url when the Pinterest token expired and could not be refreshed.

Query Parameters

Parameter	Type	Required	Description
page_size	number	Optional	1 to 100. Default 25.
bookmark	string	Optional	Pinterest pagination bookmark from the previous response.

Response Fields (data[])

Parameter	Type	Required	Description
id	string	Required	Board id, used as pinterest_board_id.
name	string	Required	Board name.
description	string \| null	Required	Board description.
privacy	string \| null	Required	Board privacy setting.
pin_count	number \| null	Required	Pins on the board.

Example Request

curl "https://sharetopus.com/api/v1/connections/5b1f0c4e-3d2a-4f6b-8c9d-0e1f2a3b4c5d/boards?page_size=25" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Media

Upload media before creating image or video posts, either by direct upload (signed URL) or by importing from a public URL. Storage paths are account-scoped: every path starts with your principal id.

POST

Create an upload URL

/api/v1/media/upload-url

Returns a signed URL for a direct upload. PUT the file bytes to upload_url, then use storage_path as media_storage_path when creating posts. Content type and size are validated against your plan limits; 403 when the storage quota would be exceeded.

Request Body

Parameter	Type	Required	Description
filename	string	Required	1 to 255 characters.
content_type	string	Required	MIME type of the file, for example video/mp4.
size_bytes	number	Required	Positive integer.

Response Fields

Parameter	Type	Required	Description
upload_url	string	Required	Signed upload URL.
storage_path	string	Required	Path to use as media_storage_path when posting.
token	string	Required	Upload token bound to the signed URL.
expires_in_seconds	number	Required	Signed URL lifetime: 7200 (2 hours).

Example Request

curl -X POST "https://sharetopus.com/api/v1/media/upload-url" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "launch.mp4", "content_type": "video/mp4", "size_bytes": 10485760 }'

POST

Attach media from a URL

/api/v1/media/attach-from-url

Downloads media from a public URL into Sharetopus storage server-side. SSRF-protected (private address ranges are blocked) and restricted to image and video content types. The filename is inferred from the URL when omitted.

Request Body

Parameter	Type	Required	Description
url	string (url)	Required	Public URL of the media file.
filename	string	Optional	1 to 255 characters. Inferred from the URL when omitted.

Response Fields

Parameter	Type	Required	Description
success	boolean	Required	True when the file was stored.
storage_path	string	Required	Path to use as media_storage_path when posting.
content_type	string	Required	Detected MIME type.
size_bytes	number	Required	Stored file size.

Example Request

curl -X POST "https://sharetopus.com/api/v1/media/attach-from-url" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/assets/launch.mp4" }'

GET

Get a view URL

/api/v1/media/{path}

Returns a short-lived signed URL to view or download a stored file. The path is the full storage path ({principal_id}/filename); paths outside your account return 403.

Query Parameters

Parameter	Type	Required	Description
expires_in_seconds	number	Optional	1 to 3600. Default 300.

Response Fields

Parameter	Type	Required	Description
view_url	string	Required	Signed view URL.
expires_in_seconds	number	Required	Lifetime of the returned URL.

Example Request

curl "https://sharetopus.com/api/v1/media/user_2f6a1c0e.../launch.mp4?expires_in_seconds=600" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

DELETE

Delete a media file

/api/v1/media/{path}

Reference-aware delete: when the file is still referenced by a scheduled or pending post, it is preserved and the response carries deleted false. Unreferenced files are removed.

Response Fields

Parameter	Type	Required	Description
storage_path	string	Required	The path acted on.
deleted	boolean	Required	False when the file is still referenced by a post.

Example Request

curl -X DELETE "https://sharetopus.com/api/v1/media/user_2f6a1c0e.../launch.mp4" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Webhooks

HTTPS event notifications instead of polling. Each delivery is HMAC-SHA256 signed with the subscription secret, which is returned exactly once at creation.

Event	Fires when
post.scheduled	A post is successfully scheduled.
post.published	A post is published to a social platform.
post.failed	Publishing a post fails.
connection.connected	An OAuth flow completes and the account is connected.
connection.expired	An account token expires and cannot be refreshed.

Verify every delivery: compute HMAC-SHA256 of the raw request body with your subscription secret and compare it to the X-Sharetopus-Signature header (sha256=<hex> format).

POST

Create a subscription

/api/v1/webhooks

Subscribes an HTTPS endpoint to 1 to 20 event types. The response is the subscription plus the signing secret; the secret is never returned again.

Request Body

Parameter	Type	Required	Description
url	string (url)	Required	HTTPS endpoint, max 2048 characters. Private addresses are rejected.
events	string[]	Required	1 to 20 event types from the table above.

Response Fields (WebhookSubscriptionDTO)

Parameter	Type	Required	Description
id	string (uuid)	Required	Subscription id.
url	string	Required	Destination HTTPS endpoint.
events	string[]	Required	Subscribed event types.
active	boolean	Required	False after repeated delivery failures disable the subscription.
failure_count	number	Required	Consecutive failed deliveries.
last_delivery_at	string \| null	Required	Last delivery attempt.
last_disabled_at	string \| null	Required	When the subscription was auto-disabled, if ever.
created_at	string	Required	Creation time.
updated_at	string	Required	Last update time.

The secret field appears only in this response. Store it immediately; recovering it later requires creating a new subscription.

Example Request

curl -X POST "https://sharetopus.com/api/v1/webhooks" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/sharetopus", "events": ["post.published", "post.failed"] }'

GET

List subscriptions

/api/v1/webhooks

All subscriptions for the account, newest first. Not paginated.

Example Request

curl "https://sharetopus.com/api/v1/webhooks" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

GET

Get a subscription

/api/v1/webhooks/{id}

One subscription by id, without the secret.

Example Request

curl "https://sharetopus.com/api/v1/webhooks/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

PATCH

Update a subscription

/api/v1/webhooks/{id}

Changes the URL, the event list, or the active flag. At least one field is required. Setting active true resets failure_count and clears last_disabled_at, re-enabling a subscription that repeated failures disabled.

Request Body

Parameter	Type	Required	Description
url	string (url)	Optional	New HTTPS endpoint, max 2048 characters.
events	string[]	Optional	Replacement event list, 1 to 20 types.
active	boolean	Optional	true re-enables a disabled subscription.

Example Request

curl -X PATCH "https://sharetopus.com/api/v1/webhooks/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": true }'

DELETE

Delete a subscription

/api/v1/webhooks/{id}

Deletes the subscription and its delivery history. Not reversible.

Response Fields

Parameter	Type	Required	Description
id	string (uuid)	Required	The deleted subscription.
deleted	boolean	Required	Always true on success.

Example Request

curl -X DELETE "https://sharetopus.com/api/v1/webhooks/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

POST

Send a test event

/api/v1/webhooks/{id}/test

Delivers a synthetic event synchronously (10 second timeout) and returns the actual delivery result, so you can debug the receiving endpoint without waiting for real traffic.

Request Body

Parameter	Type	Required	Description
event_type	string	Optional	Event type to simulate. Defaults to a webhook.test payload.

Response Fields

Parameter	Type	Required	Description
delivery_id	string (uuid)	Required	Recorded delivery.
subscription_id	string (uuid)	Required	The subscription tested.
status_code	number \| null	Required	HTTP status your endpoint returned.
latency_ms	number	Required	Round-trip latency.
delivered_at	string \| null	Required	Set when the delivery succeeded.
error_message	string \| null	Required	Set when the delivery failed.

Example Request

curl -X POST "https://sharetopus.com/api/v1/webhooks/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d/test" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "post.published" }'

GET

List deliveries

/api/v1/webhooks/{id}/deliveries

Cursor-paginated delivery log for one subscription: status codes, latency, attempts, and errors.

Query Parameters

Parameter	Type	Required	Description
limit	number	Optional	1 to 100. Default 20.
cursor	string	Optional	next_cursor from the previous page.

Response Fields (data[])

Parameter	Type	Required	Description
id	string (uuid)	Required	Delivery id.
event_type	string	Required	Delivered event type.
event_id	string	Required	Event the delivery belongs to.
status_code	number \| null	Required	HTTP status returned by the endpoint.
attempt	number	Required	Attempt counter for the event.
latency_ms	number \| null	Required	Round-trip latency.
delivered_at	string \| null	Required	Set on success.
failed_at	string \| null	Required	Set on failure.
error_message	string \| null	Required	Failure detail.
created_at	string	Required	Record creation time.

Example Request

curl "https://sharetopus.com/api/v1/webhooks/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d/deliveries?limit=20" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

POST

Replay a delivery

/api/v1/webhooks/{id}/deliveries/{delivery_id}/replay

Re-dispatches a past event through the same delivery pipeline as live events. The subscription must be active; disabled subscriptions return 403.

Response Fields

Parameter	Type	Required	Description
subscription_id	string (uuid)	Required	The subscription targeted.
original_delivery_id	string (uuid)	Required	The delivery replayed.
event_type	string	Required	Event type re-dispatched.
message	string	Required	Confirmation; a new delivery appears shortly.

Example Request

curl -X POST "https://sharetopus.com/api/v1/webhooks/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d/deliveries/7d6c5b4a-3e2f-4d1c-8b9a-0f1e2d3c4b5a/replay" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Delivery · Headers

Content-Type: application/json
X-Sharetopus-Event: post.published
X-Sharetopus-Delivery: 7d6c5b4a-3e2f-4d1c-8b9a-0f1e2d3c4b5a
X-Sharetopus-Signature: sha256=<hex(HMAC-SHA256(secret, raw_body))>
User-Agent: Sharetopus-Webhook/1.0

Delivery · Payload

{
  "event_type": "post.published",
  "event_id": "b2a1c0d9-8e7f-4a6b-5c4d-3e2f1a0b9c8d",
  "delivery_id": "7d6c5b4a-3e2f-4d1c-8b9a-0f1e2d3c4b5a",
  "created_at": "2026-07-04T18:02:11.000Z",
  "data": { "...": "event-specific fields" }
}

Analytics, history, and usage

Account-wide reads: performance metrics, the published-content log, and the current billing period's quotas and storage.

GET

List analytics

/api/v1/analytics

Account-wide metric rows, cursor-paginated on metric date. Metrics are collected after publication and may lag the platform by up to a day.

Query Parameters

Parameter	Type	Required	Description
platform	string	Optional	linkedin, tiktok, pinterest, instagram, youtube, x, or facebook.
content_id	string	Optional	Filter by platform-side content id.
days	number	Optional	Lookback window, 1 to 90. Default 30.
limit	number	Optional	1 to 100. Default 20.
cursor	string	Optional	next_cursor from the previous page.

Response Fields (data[])

Parameter	Type	Required	Description
id	string (uuid)	Required	Metric row id.
platform	string	Required	Platform the metric belongs to.
content_id	string \| null	Required	Platform-side content id.
metric_date	string	Required	Day the metrics were sampled.
views	number	Required	Views at sample time.
likes	number	Required	Likes at sample time.
comments	number	Required	Comments at sample time.
shares	number	Required	Shares at sample time.
subscribers	number	Required	Account followers or subscribers at sample time.
created_at	string	Required	Record creation time.

Example Request

curl "https://sharetopus.com/api/v1/analytics?platform=tiktok&days=30" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

GET

List content history

/api/v1/content-history

Published content records, cursor-paginated, newest first. This is the confirmation surface after immediate publishing.

Query Parameters

Parameter	Type	Required	Description
platform	string	Optional	Any of linkedin, tiktok, pinterest, instagram, facebook, threads, youtube, x.
limit	number	Optional	1 to 100. Default 20.
cursor	string	Optional	next_cursor from the previous page.

Response Fields (data[])

Parameter	Type	Required	Description
id	string (uuid)	Required	History record id.
platform	string	Required	Platform the content went to.
content_id	string	Required	Platform-side content identifier.
scheduled_post_id	string \| null	Required	Originating post, when scheduled.
title	string \| null	Required	Title, when set.
description	string \| null	Required	Body text, when set.
media_url	string \| null	Required	Public media URL, when available.
media_type	string \| null	Required	text, image, or video.
status	string \| null	Required	Platform-side publish status.
batch_id	string \| null	Required	Batch the content came from.
created_via	string	Required	Surface that created the content (rest, mcp, x402, web).
created_at	string	Required	Record creation time.

Example Request

curl "https://sharetopus.com/api/v1/content-history?platform=x&limit=10" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

GET

Get usage

/api/v1/usage

Current plan, billing period, per-action usage counters, and storage consumption against the cap.

Response Fields

Parameter	Type	Required	Description
plan	string \| null	Required	Active plan name.
status	string	Required	active, inactive, or past_due.
current_period_end	string \| null	Required	End of the current billing period.
period	string	Required	Quota period type (month).
actions	object	Required	Per-action usage counters for the period.
storage	object	Required	used_bytes, cap_bytes, and human-readable equivalents.

Example Request

curl "https://sharetopus.com/api/v1/usage" \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Response · 200

{
  "plan": "creator",
  "status": "active",
  "current_period_end": "2026-07-28T00:00:00.000Z",
  "period": "month",
  "actions": { "rest.posts.create": 42, "rest.media.upload_url": 17 },
  "storage": {
    "used_bytes": 734003200,
    "cap_bytes": 5368709120,
    "used_human": "700 MB",
    "cap_human": "5 GB"
  }
}