API reference

Schedule, publish and manage posts on every network you’ve connected to OwlKonnect, from your own code, an automation tool like n8n or Zapier, or an AI assistant. The API is included on every plan.

REST base URLhttps://app.owlkonnect.com/api/v1
MCP serverhttps://mcp.owlkonnect.com/mcp

Quick start

  1. In the app, open Settings → Developer / API and create a key. Copy it straight away: the full key is only shown once. It starts with ok_live_.
  2. Find the ids of the channels you want to post to:
curl https://app.owlkonnect.com/api/v1/channels \
  -H "Authorization: Bearer $OWLKONNECT_API_KEY"
  1. Create a post. This one publishes immediately:
curl -X POST https://app.owlkonnect.com/api/v1/posts \
  -H "Authorization: Bearer $OWLKONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "caption": "Hello from the API", "channel_ids": [12], "publish_now": true }'

Then check the result with GET /v1/posts/{id}, or register a webhook to be told when it’s done.

Authentication

Send your key on every request. Any one of these works:

Authorization: Bearer ok_live_…      (recommended)
X-API-Key: ok_live_…
?api_key=ok_live_…                    (query string, for clients that only take a URL)

Keys belong to your workspace and act with your permissions. You can revoke a key at any time in Settings → Developer / API; requests with a revoked key get a 401 that says so. In n8n, use the HTTP Request node with a header named Authorization and the value Bearer followed by your key.

Rate limits

Requests per minute, per key:

PlanRequests / minute
Trial30
Standard60
Premium120
Business300
Agency600

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get a 429 with Retry-After.

Errors

Errors are JSON with a readable message:

{ "statusCode": 400, "error": "Bad Request",
  "message": "media_urls[0]: the link opens a web page, not a file (use a direct download link)." }
StatusMeaning
400The request was invalid. message says which field and why, e.g. a media link that opens a web page.
401Missing, malformed, revoked or expired key. message says which.
402Your plan doesn’t include this (analytics and engagement need Premium), or a plan limit was reached.
404No such post, comment or webhook in your workspace.
429Rate limit reached. Wait for Retry-After seconds.

A post that is accepted but then fails on a network doesn’t error the request. The post’s status becomes failed and error holds the network’s reason.

Media

Pass files as links in media_urls. When you create the post, OwlKonnect downloads each file, works out its type from the file itself, and stores a copy. So the link only has to work at that moment: signed or expiring links are fine, and so are links without a file extension.

  • Supported: JPG, PNG, GIF, WEBP images and MP4, MOV, WEBM video.
  • Size: images up to 50 MB, videos up to 512 MB.
  • A link that can’t be used fails the request straight away with the reason (not found, a web page instead of a file, an unsupported type), rather than failing at publish time.
  • If a file takes longer than about 85 seconds to download, upload it with POST /v1/media and use the URL it returns.
  • Instagram, Pinterest and YouTube need media on every post: Pinterest an image, YouTube a video.

Network options

Settings that only apply to one network go in platform_options, grouped by network. Include only groups for networks the post goes to. A value that isn’t allowed fails the request with a message saying what is, instead of being quietly replaced.

"platform_options": {
  "youtube": { "title": "Spring menu tour", "privacy": "unlisted", "tags": ["food", "menu"] },
  "pinterest": { "board_id": "8495…", "link": "https://acme.example/menu" },
  "google_business": { "post_kind": "offer", "event_title": "20% off lunch",
    "event_start": "2026-12-01", "event_end": "2026-12-07", "offer_coupon": "LUNCH20" }
}
GroupOptions
instagramcollaborators (up to 3 usernames), location_id, reel_cover_url. One video posts as a Reel; 2–10 items as a carousel.
facebooklocation_id.
youtubetitle, privacy, tags, playlist_id, category_id, made_for_kids, notify_subscribers, embeddable, license (youtube or creativeCommon), short, thumbnail_url, comment.
xthread, reply_text, reply_delay_minutes, auto_repost_hours, community_id, share_with_followers, quote_post_id.
threadsreply_control: everyone, accounts_you_follow, mentioned_only, followers_only or parent_post_author_only.
pinterestboard_id (required for Pinterest), title, link.
telegrambutton_label and button_url (together), disable_link_preview.
blueskyreply_control (everyone, following, mentioned or nobody), thread, quote_url.
mastodonvisibility (public, unlisted, private or direct), content_warning.
google_businesspost_kind (standard, offer or event), button (BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP or CALL) and button_url, event_title, event_start, event_end (YYYY-MM-DD), offer_coupon, offer_url, offer_terms, add_to_photos, photos_only.
polloptions (2–4), duration_minutes (5–10080), multiple_choice (Mastodon only). X and Mastodon.
first_commentdelay_minutes, or only_after (likes or comments) with threshold: post the first comment once the post reaches that many.

Account, brands & channels

GET/v1/me

The workspace and role the key authenticates as. Handy as a key check.

Response
{ "user_id": 41, "org_owner_id": 41, "role": "admin", "team_role": "owner" }
GET/v1/brands

Brands (workspaces) in your account. Use a brand id to group posts or filter lists.

Response
[{ "id": 3, "name": "Acme", "handle": "acme", "website": "https://acme.example", "industry": "Retail" }]
GET/v1/channels

Connected social accounts. You need their ids to create posts.

Response
[{ "id": 12, "platform": "instagram", "account_name": "Acme Store",
   "account_handle": "acmestore", "status": "active", "brand_id": 3 }]

Posts

POST/v1/posts

Create a draft, schedule a post, or publish it right away.

With neither scheduled_at, publish_now nor add_to_queue the post is saved as a draft. Plan limits (queue size, channels) apply exactly as in the app. TikTok channels can’t be posted to through the API: TikTok requires its own posting screen, so use the composer for TikTok.

Body fieldTypeDescription
captionrequiredstringstringPost text. Up to 20,000 characters; each network’s own limit still applies.
channel_idsrequiredinteger[]integer[]Channels to post to, from GET /channels. 1–50.
scheduled_atstringstringISO 8601 time with a timezone, e.g. 2026-12-01T14:30:00Z. Must be in the future.
publish_nowbooleanbooleanPublish immediately. Overrides scheduled_at.
media_urlsstring[]string[]Up to 20 image/video links. See Media below. The first is the primary; the rest form a carousel where the network supports one.
brand_idintegerintegerBrand to file the post under.
first_commentstringstringPosted as the first comment right after publishing, where the network supports it.
youtube_titlestringstringYouTube only. Up to 100 characters. Defaults to the first line of the caption.
youtube_privacystringstringYouTube only. public (default), unlisted or private.
post_typestringstringpost (default) or story, for Facebook and Instagram Stories.
add_to_queuebooleanbooleanPut the post in your posting queue (next free slot) instead of a fixed time.
caption_overridesobjectobjectA different caption per channel: { "12": "text" }. Channels not listed use caption.
platform_optionsobjectobjectNetwork-specific settings. See Network options below.
curl -X POST https://app.owlkonnect.com/api/v1/posts \
  -H "Authorization: Bearer $OWLKONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "New arrivals are in",
    "channel_ids": [12, 48],
    "media_urls": ["https://example.com/files/clip.mp4"],
    "scheduled_at": "2026-12-01T14:30:00Z"
  }'
Response
{
  "id": 812,
  "status": "scheduled",
  "caption": "New arrivals are in",
  "media_urls": ["https://…r2.dev/media/…/clip.mp4"],
  "channels": [
    { "id": 12, "platform": "instagram", "account_name": "Acme Store", "account_handle": "acmestore",
      "post_url": null, "post_status": null, "post_error": null }
  ],
  "brand_id": 3,
  "scheduled_at": "2026-12-01T14:30:00.000Z",
  "published_at": null,
  "created_at": "2026-11-17T10:02:11.000Z",
  "updated_at": "2026-11-17T10:02:11.000Z",
  "error": null
}
GET/v1/posts

List posts, 50 per page.

Query parameterTypeDescription
statusstringstringqueue (scheduled and queued, the default), published, or drafts.
pageintegerintegerPage number, from 1.
brand_idintegerintegerOnly this brand’s posts.
Response
{ "posts": [ … ], "page": 1, "total": 37 }
GET/v1/posts/{id}

One post, its status, and for each channel the live link or why it failed.

status is one of draft, queued, scheduled, processing, published, partial, failed. Each channel carries post_status, post_url and post_error. Poll this after publish_now, or use a webhook instead.

PATCH/v1/posts/{id}

Edit a draft, scheduled, queued or failed post, or change when it goes out.

Only the fields you send change; everything else keeps its value. Published posts can’t be edited here. A failed post becomes a draft until you publish it again.

Body fieldTypeDescription
captionstringstringNew caption.
channel_idsinteger[]integer[]Replaces the channels.
media_urlsstring[]string[]Replaces the media. [] removes it.
first_commentstringstringNew first comment.
caption_overridesobjectobjectReplaces all per-channel captions. {} clears them.
platform_optionsobjectobjectMerged into the current network settings, group by group.
brand_id, post_type, youtube_title, youtube_privacyAs on create.
scheduled_atstringstringNew publish time, ISO 8601, in the future.
move_to_draftbooleanbooleantrue un-schedules the post and keeps it as a draft.
add_to_queuebooleanbooleantrue puts it in the posting queue.
POST/v1/posts/{id}/publish

Publish a draft now, or retry a post that failed on some or all channels.

Channels where the post is already live are skipped, so a retry never posts twice.

Response
{
  "id": 812,
  "status": "scheduled",
  "caption": "New arrivals are in",
  "media_urls": ["https://…r2.dev/media/…/clip.mp4"],
  "channels": [
    { "id": 12, "platform": "instagram", "account_name": "Acme Store", "account_handle": "acmestore",
      "post_url": null, "post_status": null, "post_error": null }
  ],
  "brand_id": 3,
  "scheduled_at": "2026-12-01T14:30:00.000Z",
  "published_at": null,
  "created_at": "2026-11-17T10:02:11.000Z",
  "updated_at": "2026-11-17T10:02:11.000Z",
  "error": null
}
DELETE/v1/posts/{id}

Delete a post from OwlKonnect, and optionally from the networks.

Without from_networks, anything already published stays live. This can’t be undone.

Query parameterTypeDescription
from_networksbooleanbooleantrue also removes the published post where the network allows it (Facebook, YouTube, LinkedIn and others). Default false.
Response
{ "ok": true, "removed_from": ["Facebook"], "remove_manually_on": ["Instagram"], "failed_on": [] }
GET/v1/channels/{id}/pinterest-boards

Boards of a Pinterest channel, for platform_options.pinterest.board_id.

Response
{ "boards": [{ "id": "8495…", "name": "Recipes" }] }
GET/v1/channels/{id}/youtube-playlists

Playlists of a YouTube channel, for platform_options.youtube.playlist_id.

Response
{ "playlists": [{ "id": "PL…", "title": "Tutorials", "count": 12 }] }
GET/v1/channels/{id}/youtube-categories

YouTube video categories, for platform_options.youtube.category_id.

Response
{ "categories": [{ "id": "22", "title": "People & Blogs" }] }

Media upload

POST/v1/media

Upload a file and get back a URL to pass in media_urls.

Only needed for files that aren’t reachable by a public link, or that take longer than about 85 seconds to download.

Form fieldTypeDescription
filerequiredfilefilemultipart/form-data field. Images up to 50 MB, videos up to 512 MB.
curl -X POST https://app.owlkonnect.com/api/v1/media \
  -H "Authorization: Bearer $OWLKONNECT_API_KEY" \
  -F "[email protected]"
Response
{ "id": 1903, "url": "https://…r2.dev/media/…/clip.mp4", "mime": "video/mp4", "size": 20971520 }

AI captions

Uses your OwlKonnect AI credits, or your own OpenAI/Gemini key if you added one in Settings → AI Keys. Nothing is posted.

POST/v1/ai/captions

Variations of a caption: same facts, links and tone, different wording.

Body fieldTypeDescription
captionrequiredstringstringThe caption or brief to vary.
countintegerinteger1–10, default 3.
Response
{ "captions": ["…", "…", "…"] }
POST/v1/ai/optimize-caption

Rewrite a caption to suit one network.

Body fieldTypeDescription
captionrequiredstringstringThe caption to rewrite.
platformrequiredstringstringfacebook, instagram, linkedin, x, threads, youtube, pinterest, gmb, telegram, bluesky or mastodon.
Response
{ "caption": "…" }

Analytics

Premium plan and above. On other plans these return 402.

GET/v1/analytics/overview

Totals and trends for reach, impressions, engagement and followers.

Query parameterTypeDescription
rangestringstring7d, 30d (default) or 90d.
brand_idintegerintegerOnly this brand’s channels.
channel_idintegerintegerOnly this channel.
GET/v1/analytics/channels

The same metrics broken down per channel.

Query parameterTypeDescription
rangestringstring7d, 30d (default) or 90d.
brand_idintegerintegerOnly this brand’s channels.

Comments & engagement

Premium plan and above. On other plans these return 402. Covers the networks the in-app Engagement screen covers; X comments aren’t included.

GET/v1/engagement/stats

Counts of unreplied comments and reviews, and recent volume.

Query parameterTypeDescription
brand_idintegerintegerOnly this brand.
channel_idintegerintegerOnly this channel.
Response
{ "unreplied": 14, "unreplied_reviews": 2, "this_week": 61, "last_week": 48, "this_month": 203 }
GET/v1/engagement/comments

Comments on your posts, newest first, with the post and channel inline.

Query parameterTypeDescription
unreplied_onlybooleanbooleanOnly comments nobody has replied to yet.
qstringstringSearch comment and author text.
brand_idintegerintegerOnly this brand.
channel_idintegerintegerOnly this channel.
pageintegerintegerFrom 1.
per_pageintegerinteger1–100, default 25.
Response
{ "data": [{ "id": 5521, "post_id": 17020, "platform": "instagram",
   "author_name": "Sam", "text": "Do you ship to Canada?", "has_reply": false,
   "is_hidden": false, "channel_name": "Acme Store", … }],
  "page": 1, "per_page": 25, "total": 14 }
POST/v1/engagement/comments/{id}/reply

Reply publicly under a comment, from your account.

Body fieldTypeDescription
textrequiredstringstringThe reply, 1–5,000 characters.
Response
{ "ok": true, "reply_platform_id": "18034…" }
POST/v1/engagement/comments/{id}/hide

Hide or unhide a comment. Facebook and Instagram only.

Body fieldTypeDescription
hiddenrequiredbooleanbooleantrue hides, false unhides.
DELETE/v1/engagement/comments/{id}

Delete a comment on the network itself, with its replies.

This can’t be undone. Prefer hiding where that’s enough.

GET/v1/engagement/reviews

Google Business Profile reviews, newest first, plus each location’s count and average rating.

Query parameterTypeDescription
repliedstringstringall (default), replied or unreplied.
starsstringstringComma-separated ratings, e.g. 1,2.
channel_idintegerintegerOnly this location.
brand_idintegerintegerOnly this brand.
pageintegerintegerFrom 1.
per_pageintegerinteger1–100, default 25.
Response
{ "reviews": [{ "id": 902, "channel_id": 31, "location": "Acme Store Downtown",
   "stars": 2, "text": "Waited 40 minutes", "reviewer": "Sam", "reply": null, … }],
  "total": 118, "unreplied": 9, "locations": [ … ] }
POST/v1/engagement/reviews/{id}/reply

Reply publicly to a Google review as the business. Replaces any earlier reply.

Body fieldTypeDescription
textrequiredstringstringThe reply, 1–4,000 characters.
Response
{ "ok": true, "reply": "Thanks for…" }
GET/v1/reply-templates

Your team’s saved reply templates.

Query parameterTypeDescription
scopestringstringengagement (comments, default) or reviews.
brand_idintegerintegerInclude this brand’s templates.

Webhooks

Get a POST to your server when a post finishes publishing, instead of polling. See Receiving webhooks below for the payload and signature.

POST/v1/webhooks

Register an endpoint. The response includes the signing secret, shown only this once.

Body fieldTypeDescription
urlrequiredstringstringA public HTTPS URL.
eventsstring[]string[]post.published and/or post.failed. Defaults to both.
Response
{ "id": 7, "url": "https://example.com/hooks/owlkonnect",
  "events": ["post.published", "post.failed"], "active": true,
  "last_status": null, "last_delivery_at": null,
  "created_at": "2026-11-17T10:02:11.000Z", "secret": "whsec_…" }
GET/v1/webhooks

Your endpoints, with the last delivery status of each.

DELETE/v1/webhooks/{id}

Remove an endpoint.

Response
{ "ok": true }

Receiving webhooks

When a post finishes, each matching endpoint gets a JSON POST. post.published means it went out on at least one channel; post.failed means every channel failed.

POST /hooks/owlkonnect
Content-Type: application/json
User-Agent: OwlKonnect-Webhooks/1
X-OwlKonnect-Event: post.published
X-OwlKonnect-Signature: sha256=5d41402abc4b2a76b9719d911017c592…

{
  "event": "post.published",
  "created_at": "2026-12-01T14:30:09.000Z",
  "data": { "post_id": 812, "status": "published", "caption": "New arrivals are in", "error": null }
}

Check the signature before trusting a delivery: it is an HMAC-SHA256 of the raw request body, keyed with your endpoint’s secret.

import crypto from 'node:crypto';

function isFromOwlKonnect(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return signatureHeader.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Reply with any 2xx within 10 seconds. Other responses are retried up to 5 times with growing delays, and an endpoint that keeps failing is switched off; create it again once it’s fixed.

MCP server

AI assistants that support MCP (Claude, ChatGPT and agent frameworks) can use OwlKonnect directly. Add https://mcp.owlkonnect.com/mcp as a connector and approve access when you’re asked to sign in, or send an API key the same way as for the REST API. The tools map onto the endpoints above:

ToolWhat it does
get_meWhich account the connection is signed in as.
list_brandsYour brands.
list_channelsConnected accounts and their ids.
create_postDraft, schedule, queue or publish, with media, stories, per-channel captions and network options.
update_postEdit or reschedule a post that hasn’t gone out yet.
publish_postPublish a draft now, or retry a failed post.
delete_postDelete a post, optionally from the networks too.
list_postsQueue, published or drafts.
get_postOne post, its status, and each channel’s live link or failure reason.
list_pinterest_boardsBoard ids for Pinterest posts.
list_youtube_playlistsPlaylist ids for YouTube posts.
list_youtube_categoriesCategory ids for YouTube posts.
generate_caption_variationsCaption variations with OwlKonnect AI.
optimize_captionRewrite a caption for one network with OwlKonnect AI.
get_analyticsOverview metrics (Premium+).
get_channel_analyticsMetrics per channel (Premium+).
list_commentsComments on your posts (Premium+).
get_engagement_statsUnreplied counts and volume (Premium+).
reply_to_commentReply under a comment (Premium+).
hide_commentHide or unhide a Facebook/Instagram comment (Premium+).
delete_commentDelete a Facebook/Instagram comment (Premium+).
list_reviewsGoogle Business Profile reviews (Premium+).
reply_to_reviewReply to a Google review (Premium+).
list_reply_templatesYour saved reply templates.

More on connecting an assistant: OwlKonnect for AI assistants.

Questions about the API?

Use the chat in the app, or write to us from the contact page.

Get an API key →Contact us