SOSPosting

https://sosposting.com/developers
Admin
SOSPosting is a social media publishing API and platform that enables automated cross-posting to...
Tokens:3,808
Snippets:24
Trust Score:3.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Authentication header example

Source: https://sosposting.com/developers

Shows the required Authorization header format using a Bearer token with the sosp_ prefix. The key is scoped to the business it was created in and should be stored securely.

```http
Authorization: Bearer sosp_<your key>
```

--------------------------------

### GET /api/v1/posts/:id response

Source: https://sosposting.com/developers

Example JSON response showing post status and target-specific metrics.

```json
{
  "id": "cmcz...",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "scheduledAt": null,
  "status": "POSTED",
  "targets": [
    {
      "provider": "INSTAGRAM",
      "status": "POSTED",
      "externalId": "1789...",
      "externalUrl": "https://www.instagram.com/p/...",
      "error": null,
      "metrics": { "views": 1200, "likes": 88, "comments": 7 }
    }
  ]
}
```

--------------------------------

### GET /api/v1/posts/:id request

Source: https://sosposting.com/developers

Example cURL request to poll post status and metrics using an authorization bearer token.

```bash
curl https://app.sosposting.com/api/v1/posts/cmcz... \
  -H "Authorization: Bearer sosp_..."
```

--------------------------------

### GET /api/v1/posts/:id

Source: https://sosposting.com/developers

Retrieves the status and metrics for a specific post. Use this endpoint to poll the post to see how delivery went and how the post performs. Delivery status is returned for every target, and engagement metrics are polled from Facebook, Instagram, and YouTube only.

```APIDOC
## GET /api/v1/posts/:id

### Description
Poll the post to see how delivery went and how the post performs. Delivery status is returned for every target; engagement metrics are polled from Facebook, Instagram and YouTube only. Metrics are refreshed at most once per hour, on demand.

### Method
GET

### Endpoint
/api/v1/posts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the post.

### Request Example
curl https://app.sosposting.com/api/v1/posts/cmcz... \
  -H "Authorization: Bearer sosp_..."

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the post.
- **createdAt** (string) - The creation timestamp of the post.
- **scheduledAt** (string or null) - The scheduled time of the post, or null if not scheduled.
- **status** (string) - Post-level status: QUEUED, SCHEDULED, PROCESSING, POSTED, PARTIAL, FAILED, or SKIPPED.
- **targets** (array) - List of delivery targets.
  - **provider** (string) - The platform name (e.g., INSTAGRAM).
  - **status** (string) - Delivery status for this target.
  - **externalId** (string) - External identifier on the platform.
  - **externalUrl** (string or null) - URL to the post on the platform, or null if not publicly live.
  - **error** (string or null) - Error message if any.
  - **metrics** (object or null) - Engagement metrics for supported platforms (FACEBOOK, INSTAGRAM, YOUTUBE). Null for other providers or before first refresh.
    - **views** (number) - Number of views (video posts only).
    - **likes** (number) - Number of likes.
    - **comments** (number) - Number of comments.
    - **shares** (number) - Number of shares (Facebook only).
  - **metricsAt** (string) - Timestamp of last metrics refresh.

#### Response Example
{
  "id": "cmcz...",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "scheduledAt": null,
  "status": "POSTED",
  "targets": [
    {
      "provider": "INSTAGRAM",
      "status": "POSTED",
      "externalId": "1789...",
      "externalUrl": "https://www.instagram.com/p/...",
      "error": null,
      "metrics": { "views": 1200, "likes": 88, "comments": 7 }
    }
  ]
}

### Error Handling
- **404 Not Found** - Unknown or foreign post ids return 404.

### Notes
- TikTok targets show PENDING_USER while the video sits in the account's TikTok drafts waiting for a manual publish - it isn't publicly live yet, so it has no externalUrl.
- metrics is populated for FACEBOOK, INSTAGRAM and YOUTUBE targets only; every other provider (TikTok, Pinterest, LinkedIn, Threads, Bluesky, WordPress, Shopify) always returns metrics: null.
- Even on a supported platform it is null until the first refresh after delivery, and individual keys are omitted when the platform won't report them - shares comes from Facebook only, and views from video posts.
- metricsAt tells you when a target's metrics were last refreshed.
```

--------------------------------

### POST /api/v1/posts

Source: https://sosposting.com/developers

Creates a post and fans it out to the targeted platforms. Accepts post type, media URL, copy, providers, AI captioning flag, and optional scheduling time. Returns 201 with post ID and per-platform targets.

```APIDOC
## POST /api/v1/posts

### Description
Creates a post and publishes it to the specified platforms. Supports AI-generated captions and scheduling.

### Method
POST

### Endpoint
https://app.sosposting.com/api/v1/posts

### Parameters
#### Request Body
- **type** (string) - Required - Post type: "reel", "social", "product", or "blog".
- **mediaUrl** (string) - Optional - Public https URL of the image or video. Use the presign endpoint if you don't host media yourself.
- **title** (string) - Optional - Title of the post.
- **caption** (string) - Optional - Caption text.
- **providers** (array of strings) - Optional - List of platform identifiers (e.g., ["INSTAGRAM","FACEBOOK","TIKTOK"]). Defaults to all eligible connected platforms.
- **useAi** (boolean) - Optional - Default true. Set false to publish text verbatim.
- **scheduledAt** (string) - Optional - ISO 8601 timestamp for scheduling.

### Request Example
```
curl -X POST https://app.sosposting.com/api/v1/posts \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reel",
    "mediaUrl": "https://example.com/clip.mp4",
    "title": "Summer drop",
    "caption": "Our new summer collection is live",
    "providers": ["INSTAGRAM", "FACEBOOK", "YOUTUBE"],
    "useAi": true,
    "scheduledAt": "2026-08-01T09:00:00Z"
  }'
```

### Response
#### Success Response (201)
- **id** (string) - Post ID.
- **scheduledAt** (string) - Scheduled timestamp.
- **targets** (array) - List of targets, each with id and status.

#### Response Example
```
{
  "id": "cmcz...",
  "scheduledAt": "2026-08-01T09:00:00.000Z",
  "targets": [
    { "id": "t1...", "status": "QUEUED" },
    { "id": "t2...", "status": "QUEUED" }
  ]
}
```
```

--------------------------------

### POST /api/v1/media/presign and PUT upload

Source: https://sosposting.com/developers

Request a presigned upload URL, receive the upload details, and perform the PUT request to upload the media file. Images are limited to 25 MB and videos to 50 MB.

```bash
curl -X POST https://app.sosposting.com/api/v1/media/presign \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 10485760
  }'
```

```json
{
  "uploadUrl": "https://...r2.cloudflarestorage.com/...",  // PUT the raw bytes here
  "publicUrl": "https://media.../uploads/....mp4",         // use as mediaUrl
  "key": "uploads/....mp4"
}
```

```bash
curl -X PUT "<uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --data-binary @clip.mp4
```

--------------------------------

### Create a post with curl

Source: https://sosposting.com/developers

Sends a POST request to /api/v1/posts with a JSON payload specifying type, mediaUrl, title, caption, providers, useAi, and scheduledAt. Returns 201 with a post id and target statuses.

```bash
curl -X POST https://app.sosposting.com/api/v1/posts \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reel",
    "mediaUrl": "https://example.com/clip.mp4",
    "title": "Summer drop",
    "caption": "Our new summer collection is live",
    "providers": ["INSTAGRAM", "FACEBOOK", "YOUTUBE"],
    "useAi": true,
    "scheduledAt": "2026-08-01T09:00:00Z"
  }'
```

```json
{
  "id": "cmcz...",
  "scheduledAt": "2026-08-01T09:00:00.000Z",
  "targets": [
    { "id": "t1...", "status": "QUEUED" },
    { "id": "t2...", "status": "QUEUED" }
  ]
}
```

--------------------------------

### POST /api/v1/media/presign

Source: https://sosposting.com/developers

Requests a presigned upload URL for media. After receiving the response, PUT the raw bytes to uploadUrl and use the returned publicUrl as mediaUrl when creating a post.

```APIDOC
## POST /api/v1/media/presign

### Description
Ask for a presigned upload, PUT the bytes, then use the returned publicUrl as mediaUrl when creating the post.

### Method
POST

### Endpoint
https://app.sosposting.com/api/v1/media/presign

### Parameters
#### Request Body
- filename (string) - Required - The name of the file to upload.
- contentType (string) - Required - The MIME type of the media (e.g., video/mp4).
- sizeBytes (integer) - Required - The size of the media in bytes. Missing it returns 400.

### Request Example
curl -X POST https://app.sosposting.com/api/v1/media/presign \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 10485760
  }'

### Response
#### Success Response (200)
- uploadUrl (string) - The URL to PUT the raw bytes to.
- publicUrl (string) - The URL to use as mediaUrl when creating the post.
- key (string) - The storage key for the uploaded media.

#### Response Example
{
  "uploadUrl": "https://...r2.cloudflarestorage.com/...",
  "publicUrl": "https://media.../uploads/....mp4",
  "key": "uploads/....mp4"
}

### PUT Upload
After receiving the presign response, PUT the raw bytes to the uploadUrl.

#### Request Example
curl -X PUT "<uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --data-binary @clip.mp4

### Limits
- Images up to 25 MB.
- Videos up to 50 MB.
- sizeBytes is required (missing it returns 400).
- Unsupported content types are rejected with 415.
- Oversize files are rejected with 413.
- Presign requests are rate-limited per business (429).

### Errors
Errors return a JSON body { "error": "...", "code": "..." } with a conventional status code.
- 400 bad request
- 401 bad key
- 402 not enough tokens
- 404 not found
- 413/415 media limits
- 429 rate limited

```

--------------------------------

### API Error Response Format

Source: https://sosposting.com/developers

Standard JSON structure returned for API errors, including a machine-readable code.

```json
{ "error": "...", "code": "..." }
```
Tokens:
Raw