| Call | What it does |
|---|
POST /api/v1/posts | Schedules a post (multipart); returns its id |
|---|
GET /api/v1/posts | Your posts, newest first; filter by status, phone or date |
|---|
GET /api/v1/posts/{id} | One post and its status |
|---|
PATCH /api/v1/posts/{id} | New caption or time, while it is still scheduled |
|---|
DELETE /api/v1/posts/{id} | Cancels a scheduled post; removes a finished one from your list |
|---|
POST /api/v1/posts/{id}/retry | Runs a failed post again on the same phone, within 24 hours |
|---|
Schedule a post
Send the post as multipart/form-data to POST /api/v1/posts. One call
schedules one post; with phones, the same post goes to each phone, 8 to 10 minutes
apart.
| Field | Required | Notes |
|---|
type | yes | instagram_reel, instagram_post, tiktok or facebook_reel |
|---|
phone | one of phone, account, phones | The id or name from GET /api/v1/phones, e.g. iPhone 1 |
|---|
account | | The name you gave a phone on the scheduler page, with or without @, e.g. @yourbrand |
|---|
phones | | Several phones, comma separated, up to 25, e.g. iPhone 1, iPhone 2; each posts 8 to 10 minutes after the previous one |
|---|
media | yes | One MP4 or MOV video for reels and TikTok; 1 to 10 photos or videos for an Instagram post (repeat media). Up to 100 MB per call |
|---|
caption | no | Up to 2,200 characters, emoji included |
|---|
post_at | yes | ISO 8601 with your time zone (2026-11-02T18:00:00+01:00), a Unix time, or now; up to 60 days ahead |
|---|
max_delay_minutes | no | Posts at a random moment 8 to this many minutes after post_at: 8 to 60, default 12. 0 posts on time |
|---|
music | no | Instagram reels: a song name; the phone finds the track and adds it |
|---|
hide_likes | no | Instagram reels: true hides the like count. Not with trial_reel |
|---|
trial_reel | no | Instagram reels: true posts it as a trial reel |
|---|
warmup_after | no | Instagram reels and posts: true runs a 14 to 18 minute Instagram warm-up after the post. Off unless you send it |
|---|
Example call:
curl -X POST https://mkyremote.com/api/v1/posts \
-H "Authorization: Bearer YOUR_KEY" \
-A "YourCompany/1.0" \
-F type=instagram_reel \
-F "phone=iPhone 1" \
-F post_at=2026-11-02T18:00:00+01:00 \
-F "caption=Monday drop #brand" \
-F [email protected]
The answer comes right away, with status 201:
{"id": "3f8c2a1e-7b4d-4c9e-a1f2-5d6e7f8a9b0c", "status": "scheduled", "count": 1,
"posts_between": ["2026-11-02T17:08:00Z", "2026-11-02T17:12:00Z"],
"posts": [{"id": "3f8c2a1e-7b4d-4c9e-a1f2-5d6e7f8a9b0c", "status": "scheduled",
"type": "instagram_reel", "phone": {"id": "00008030-…", "name": "iPhone 1"},
"caption": "Monday drop #brand", "scheduled_for": "2026-11-02T17:09:41Z",
"started_at": null, "finished_at": null, "result": null,
"media": [{"name": "video.mp4"}],
"options": {"music": null, "hide_likes": false, "trial_reel": false,
"warmup_after": false},
"source": "api", "created_at": "2026-10-29T10:15:00Z"}]}
Keep the id: it is how you follow, change or cancel the post.
posts_between is when the first phone posts; with phones, each post in
posts has its own scheduled_for.
| Status | Meaning | What you can do |
|---|
scheduled | Waiting for its time | Change it (PATCH) or cancel it (DELETE) |
|---|
posting | The phone is publishing it now | Wait; it can no longer be changed or cancelled |
|---|
posted | Published | Remove it from your list (DELETE) |
|---|
failed | Not published; result says why, e.g. "Share button not found" | Retry it within 24 hours (POST /api/v1/posts/{id}/retry), or remove it |
|---|
cancelled | Cancelled by you; its media is deleted | Remove it from your list, or send it again |
|---|
Follow, change or cancel
- Follow it with
GET /api/v1/posts/{id}: its status moves from
scheduled to posting to posted, or to failed with the reason in result.
- A failed attempt is usually retried once by itself a minute later; meanwhile the
post shows scheduled and
result reads Retrying after: ….
- Posts stay in your list for 24 hours after they finish, failed ones for 7
days.
- To change a scheduled post, send JSON with
caption,
post_at or both. A new post_at gets a new random delay, like a new post; add
max_delay_minutes to set it (0 posts on time).
- To list your posts, filter
GET /api/v1/posts with
status, phone, since, until (by scheduled time)
and limit (up to 200, default 50). The list also holds what you scheduled on the
website; source says where each one came from (api, web, or
vault for the Media library).
Change a scheduled post:
curl -X PATCH https://mkyremote.com/api/v1/posts/3f8c2a1e-7b4d-4c9e-a1f2-5d6e7f8a9b0c \
-H "Authorization: Bearer YOUR_KEY" -A "YourCompany/1.0" \
-H "Content-Type: application/json" \
-d '{"caption": "New text", "post_at": "2026-11-03T18:00:00+01:00"}'
List the failed ones:
curl "https://mkyremote.com/api/v1/posts?status=failed&limit=20" \
-H "Authorization: Bearer YOUR_KEY" -A "YourCompany/1.0"
# → {"posts": [...], "count": 2, "total": 2}