Quick Start

This guide walks you through creating and scheduling a media post from scratch: fetching a profile, uploading a file, and publishing to a social network, all in a few API calls.

Prerequisites

Before you begin:

You have an App ID and API Key from app.swonkie.com/settings/workspace/public-api

At least one social profile is connected to your workspace

You have an image or video file ready to upload

Step 1 - Get your Profile ID

Fetch the list of connected profiles in your workspace. You need the id of the profile you want to publish to.

Response item shape

{
  "id": "Tjg3YjhSU2xZREFqM1RqOTRnZTdpZz09",
  "name": "Brand Official Page",
  "username": "brandofficial",
  "net": {
    "name": "Facebook",
    "code": "facebook"
  },
  "statusLevel": "OK"
}

Use the id value as profileId in the following steps.

Step 2 - Upload your media

Uploading media is a three-step process: initiate the upload, send the file, then confirm.

2.1 - Initiate the upload

The response includes a temporary uploadUrl (expires in ~15 minutes) and the mediaId you will use to confirm and reference the upload.

2.2 - Upload the file

Send the raw file binary directly to the uploadUrl. No Swonkie auth headers are needed here, the URL is pre-signed.

2.3 - Confirm the upload

After sending the file, confirm the upload. Without this call the media stays in UPLOADING status and will be deleted.

2.4 - Wait for processing

Poll GET /v2/media/{mediaId} until status is SUCCESS.

The mediaId is also the mediaLibId, used when referencing this file in a post.

Step 3 - Create the post

With a profileId and a confirmed mediaId, create the post. Setting publishAt saves it as a DRAFT with a scheduled time. The post is not yet queued for publishing until you explicitly schedule it in the next step.

Step 4 - Schedule the post

Move the post to SCHEDULED by calling the stage transition endpoint with the schedule action. This validates the post and queues it for publication at the publishAt time.

A 200 response with stage: "SCHEDULED" confirms the post is queued for publication at the specified time.

What's next

Posts: full reference for post types, stages, and network-specific options

Media: upload flow details, supported formats, and status lifecycle

Profiles: filtering profiles by network and checking connection status

Insights: pulling performance metrics for profiles and competitors

Prerequisites#

Step 1 - Get your Profile ID#

Step 2 - Upload your media#

2.1 - Initiate the upload#

2.2 - Upload the file#

2.3 - Confirm the upload#

2.4 - Wait for processing#

Step 3 - Create the post#

Step 4 - Schedule the post#

What's next#