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.
https://app.owlkonnect.com/api/v1https://mcp.owlkonnect.com/mcpQuick start
- 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_. - 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"
- 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:
| Plan | Requests / minute |
|---|---|
| Trial | 30 |
| Standard | 60 |
| Premium | 120 |
| Business | 300 |
| Agency | 600 |
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)." }| Status | Meaning |
|---|---|
400 | The request was invalid. message says which field and why, e.g. a media link that opens a web page. |
401 | Missing, malformed, revoked or expired key. message says which. |
402 | Your plan doesn’t include this (analytics and engagement need Premium), or a plan limit was reached. |
404 | No such post, comment or webhook in your workspace. |
429 | Rate 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" }
}| Group | Options |
|---|---|
instagram | collaborators (up to 3 usernames), location_id, reel_cover_url. One video posts as a Reel; 2–10 items as a carousel. |
facebook | location_id. |
youtube | title, privacy, tags, playlist_id, category_id, made_for_kids, notify_subscribers, embeddable, license (youtube or creativeCommon), short, thumbnail_url, comment. |
x | thread, reply_text, reply_delay_minutes, auto_repost_hours, community_id, share_with_followers, quote_post_id. |
threads | reply_control: everyone, accounts_you_follow, mentioned_only, followers_only or parent_post_author_only. |
pinterest | board_id (required for Pinterest), title, link. |
telegram | button_label and button_url (together), disable_link_preview. |
bluesky | reply_control (everyone, following, mentioned or nobody), thread, quote_url. |
mastodon | visibility (public, unlisted, private or direct), content_warning. |
google_business | post_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. |
poll | options (2–4), duration_minutes (5–10080), multiple_choice (Mastodon only). X and Mastodon. |
first_comment | delay_minutes, or only_after (likes or comments) with threshold: post the first comment once the post reaches that many. |
Account, brands & channels
/v1/meThe workspace and role the key authenticates as. Handy as a key check.
{ "user_id": 41, "org_owner_id": 41, "role": "admin", "team_role": "owner" }/v1/brandsBrands (workspaces) in your account. Use a brand id to group posts or filter lists.
[{ "id": 3, "name": "Acme", "handle": "acme", "website": "https://acme.example", "industry": "Retail" }]/v1/channelsConnected social accounts. You need their ids to create posts.
[{ "id": 12, "platform": "instagram", "account_name": "Acme Store",
"account_handle": "acmestore", "status": "active", "brand_id": 3 }]Posts
/v1/postsCreate 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 field | Type | Description |
|---|---|---|
captionrequiredstring | string | Post 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_atstring | string | ISO 8601 time with a timezone, e.g. 2026-12-01T14:30:00Z. Must be in the future. |
publish_nowboolean | boolean | Publish 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_idinteger | integer | Brand to file the post under. |
first_commentstring | string | Posted as the first comment right after publishing, where the network supports it. |
youtube_titlestring | string | YouTube only. Up to 100 characters. Defaults to the first line of the caption. |
youtube_privacystring | string | YouTube only. public (default), unlisted or private. |
post_typestring | string | post (default) or story, for Facebook and Instagram Stories. |
add_to_queueboolean | boolean | Put the post in your posting queue (next free slot) instead of a fixed time. |
caption_overridesobject | object | A different caption per channel: { "12": "text" }. Channels not listed use caption. |
platform_optionsobject | object | Network-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"
}'{
"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
}/v1/postsList posts, 50 per page.
| Query parameter | Type | Description |
|---|---|---|
statusstring | string | queue (scheduled and queued, the default), published, or drafts. |
pageinteger | integer | Page number, from 1. |
brand_idinteger | integer | Only this brand’s posts. |
{ "posts": [ … ], "page": 1, "total": 37 }/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.
/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 field | Type | Description |
|---|---|---|
captionstring | string | New caption. |
channel_idsinteger[] | integer[] | Replaces the channels. |
media_urlsstring[] | string[] | Replaces the media. [] removes it. |
first_commentstring | string | New first comment. |
caption_overridesobject | object | Replaces all per-channel captions. {} clears them. |
platform_optionsobject | object | Merged into the current network settings, group by group. |
brand_id, post_type, youtube_title, youtube_privacy | As on create. | |
scheduled_atstring | string | New publish time, ISO 8601, in the future. |
move_to_draftboolean | boolean | true un-schedules the post and keeps it as a draft. |
add_to_queueboolean | boolean | true puts it in the posting queue. |
/v1/posts/{id}/publishPublish 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.
{
"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
}/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 parameter | Type | Description |
|---|---|---|
from_networksboolean | boolean | true also removes the published post where the network allows it (Facebook, YouTube, LinkedIn and others). Default false. |
{ "ok": true, "removed_from": ["Facebook"], "remove_manually_on": ["Instagram"], "failed_on": [] }/v1/channels/{id}/pinterest-boardsBoards of a Pinterest channel, for platform_options.pinterest.board_id.
{ "boards": [{ "id": "8495…", "name": "Recipes" }] }/v1/channels/{id}/youtube-playlistsPlaylists of a YouTube channel, for platform_options.youtube.playlist_id.
{ "playlists": [{ "id": "PL…", "title": "Tutorials", "count": 12 }] }/v1/channels/{id}/youtube-categoriesYouTube video categories, for platform_options.youtube.category_id.
{ "categories": [{ "id": "22", "title": "People & Blogs" }] }Media upload
/v1/mediaUpload 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 field | Type | Description |
|---|---|---|
filerequiredfile | file | multipart/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]"
{ "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.
/v1/ai/captionsVariations of a caption: same facts, links and tone, different wording.
| Body field | Type | Description |
|---|---|---|
captionrequiredstring | string | The caption or brief to vary. |
countinteger | integer | 1–10, default 3. |
{ "captions": ["…", "…", "…"] }/v1/ai/optimize-captionRewrite a caption to suit one network.
| Body field | Type | Description |
|---|---|---|
captionrequiredstring | string | The caption to rewrite. |
platformrequiredstring | string | facebook, instagram, linkedin, x, threads, youtube, pinterest, gmb, telegram, bluesky or mastodon. |
{ "caption": "…" }Analytics
Premium plan and above. On other plans these return 402.
/v1/analytics/overviewTotals and trends for reach, impressions, engagement and followers.
| Query parameter | Type | Description |
|---|---|---|
rangestring | string | 7d, 30d (default) or 90d. |
brand_idinteger | integer | Only this brand’s channels. |
channel_idinteger | integer | Only this channel. |
/v1/analytics/channelsThe same metrics broken down per channel.
| Query parameter | Type | Description |
|---|---|---|
rangestring | string | 7d, 30d (default) or 90d. |
brand_idinteger | integer | Only 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.
/v1/engagement/statsCounts of unreplied comments and reviews, and recent volume.
| Query parameter | Type | Description |
|---|---|---|
brand_idinteger | integer | Only this brand. |
channel_idinteger | integer | Only this channel. |
{ "unreplied": 14, "unreplied_reviews": 2, "this_week": 61, "last_week": 48, "this_month": 203 }/v1/engagement/commentsComments on your posts, newest first, with the post and channel inline.
| Query parameter | Type | Description |
|---|---|---|
unreplied_onlyboolean | boolean | Only comments nobody has replied to yet. |
qstring | string | Search comment and author text. |
brand_idinteger | integer | Only this brand. |
channel_idinteger | integer | Only this channel. |
pageinteger | integer | From 1. |
per_pageinteger | integer | 1–100, default 25. |
{ "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 }/v1/engagement/comments/{id}/replyReply publicly under a comment, from your account.
| Body field | Type | Description |
|---|---|---|
textrequiredstring | string | The reply, 1–5,000 characters. |
{ "ok": true, "reply_platform_id": "18034…" }/v1/engagement/comments/{id}/hideHide or unhide a comment. Facebook and Instagram only.
| Body field | Type | Description |
|---|---|---|
hiddenrequiredboolean | boolean | true hides, false unhides. |
/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.
/v1/engagement/reviewsGoogle Business Profile reviews, newest first, plus each location’s count and average rating.
| Query parameter | Type | Description |
|---|---|---|
repliedstring | string | all (default), replied or unreplied. |
starsstring | string | Comma-separated ratings, e.g. 1,2. |
channel_idinteger | integer | Only this location. |
brand_idinteger | integer | Only this brand. |
pageinteger | integer | From 1. |
per_pageinteger | integer | 1–100, default 25. |
{ "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": [ … ] }/v1/engagement/reviews/{id}/replyReply publicly to a Google review as the business. Replaces any earlier reply.
| Body field | Type | Description |
|---|---|---|
textrequiredstring | string | The reply, 1–4,000 characters. |
{ "ok": true, "reply": "Thanks for…" }/v1/reply-templatesYour team’s saved reply templates.
| Query parameter | Type | Description |
|---|---|---|
scopestring | string | engagement (comments, default) or reviews. |
brand_idinteger | integer | Include 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.
/v1/webhooksRegister an endpoint. The response includes the signing secret, shown only this once.
| Body field | Type | Description |
|---|---|---|
urlrequiredstring | string | A public HTTPS URL. |
eventsstring[] | string[] | post.published and/or post.failed. Defaults to both. |
{ "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_…" }/v1/webhooksYour endpoints, with the last delivery status of each.
/v1/webhooks/{id}Remove an endpoint.
{ "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:
| Tool | What it does |
|---|---|
get_me | Which account the connection is signed in as. |
list_brands | Your brands. |
list_channels | Connected accounts and their ids. |
create_post | Draft, schedule, queue or publish, with media, stories, per-channel captions and network options. |
update_post | Edit or reschedule a post that hasn’t gone out yet. |
publish_post | Publish a draft now, or retry a failed post. |
delete_post | Delete a post, optionally from the networks too. |
list_posts | Queue, published or drafts. |
get_post | One post, its status, and each channel’s live link or failure reason. |
list_pinterest_boards | Board ids for Pinterest posts. |
list_youtube_playlists | Playlist ids for YouTube posts. |
list_youtube_categories | Category ids for YouTube posts. |
generate_caption_variations | Caption variations with OwlKonnect AI. |
optimize_caption | Rewrite a caption for one network with OwlKonnect AI. |
get_analytics | Overview metrics (Premium+). |
get_channel_analytics | Metrics per channel (Premium+). |
list_comments | Comments on your posts (Premium+). |
get_engagement_stats | Unreplied counts and volume (Premium+). |
reply_to_comment | Reply under a comment (Premium+). |
hide_comment | Hide or unhide a Facebook/Instagram comment (Premium+). |
delete_comment | Delete a Facebook/Instagram comment (Premium+). |
list_reviews | Google Business Profile reviews (Premium+). |
reply_to_review | Reply to a Google review (Premium+). |
list_reply_templates | Your 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.