Skip to content

API docs

How keys, connected accounts and posts fit together, with the exact requests and responses.

Preview docs. The API opens with X and LinkedIn around 1 Dec 2026. Instagram, Facebook and TikTok follow their platform app reviews. Shapes may change before v1.

On this page

Overview

Postkey is a REST API for posting to social networks. You send one request with content and a list of connected accounts. Postkey publishes to each network and tells you what happened on each one.

Base URL

All requests go to:

Base URLtext
1https://api.postkey.dev

Send JSON bodies with Content-Type: application/json and your credential in the Authorization header as a Bearer token.

Two kinds of credentials

There are two kinds of credentials, and they can do different things.

Credential Looks like What it can do Where it lives
Account secret pk_live_… Create and change keys, create connect links, read the activity log Your server only
Scoped key, per customer pk_cust_… Post and schedule to the accounts listed on that key, within its limits Your server, or the customer's workflow
Scoped key, per agent pk_agent_… Same as a customer key, for one AI agent or workflow The agent's config

Never ship the account secret to a client, browser or agent. It can create keys and change limits. Give clients and agents a scoped key instead. A scoped key can only post, and only where you allowed it.

A request with the account secret:

Account secrethttp
1POST /v1/keys2Authorization: Bearer pk_live_…3 4{5  "name": "customer_42",6  "accounts": [7    "acc_ig_123",8    "acc_li_456",9    "acc_x_789"10  ],11  "dailyPostLimit": 20,12  "monthlySpendLimit": 1513}

A request with a customer's scoped key:

Scoped keyhttp
1POST /v1/posts2Authorization: Bearer pk_cust_42_…3 4{5  "content": "Hello world!",6  "accounts": [7    "acc_x_789",8    "acc_li_456"9  ]10}

How you choose between a pk_cust_ and a pk_agent_ prefix when you create a key: details before launch.

Quickstart

Three steps from nothing to a post on X and LinkedIn, the two networks open at launch.

1. Get your account secret

When the API opens you sign up and get your account secret (pk_live_…). Keep it on your server. Want in before that? Book a call.

2. Connect accounts

Your client signs in to each network through a connect link. When they finish, each connected account gets an ID like acc_li_456. See Connecting accounts for the full flow.

3. Make a key and post

Create a scoped key for that client with the accounts it may post to:

Create a keyhttp
1POST /v1/keys2Authorization: Bearer pk_live_…3 4{5  "name": "customer_42",6  "accounts": [7    "acc_ig_123",8    "acc_li_456",9    "acc_x_789"10  ],11  "dailyPostLimit": 20,12  "monthlySpendLimit": 1513}

Then post with that client's key. With curl:

curlbash
1curl https://api.postkey.dev/v1/posts \2  -H "Authorization: Bearer pk_cust_42_…" \3  -H "Content-Type: application/json" \4  -d '{ "content": "Hello world!", "accounts": ["acc_x_789", "acc_li_456"] }'

With fetch in JavaScript:

post.jsjs
1const res = await fetch("https://api.postkey.dev/v1/posts", {2  method: "POST",3  headers: {4    "Authorization": `Bearer ${process.env.POSTKEY_KEY}`,5    "Content-Type": "application/json",6  },7  body: JSON.stringify({8    content: "Hello world!",9    accounts: [10      "acc_x_789",11      "acc_li_456"12    ]13  }),14});15const post = await res.json();

You get one result per account. A response for a post to three networks looks like this:

Responsejson
1{2  "id": "post_8f21c",3  "status": "published",4  "results": [5    {6      "account": "acc_ig_123",7      "platform": "instagram",8      "status": "published",9      "url": "https://www.instagram.com/p/…"10    },11    {12      "account": "acc_li_456",13      "platform": "linkedin",14      "status": "published",15      "url": "https://www.linkedin.com/feed/update/…"16    },17    {18      "account": "acc_x_789",19      "platform": "x",20      "status": "published",21      "url": "https://x.com/acme/status/…"22    }23  ]24}

Connecting accounts

Proposed

This is how you connect your clients' social accounts without ever holding their passwords. The endpoint and webhook on this page are a draft and may change before v1.

How it works

  1. Your server asks Postkey for a connect link for one of your keys and one network.
  2. You send your client to that link. They sign in on the network's own login screen and approve access.
  3. Postkey runs the OAuth exchange, stores the tokens and keeps them fresh.
  4. The client lands back on your redirectUrl. The new account ID is attached to that key, and you get an account.connected webhook.

You never see or store passwords or refresh tokens. You only keep account IDs like acc_li_456.

Whose app your clients see

Ours. They see Postkey on each network's login screen. Your clients don't need developer accounts or their own platform apps.

Call this with your account secret.

Requesthttp
1POST /v1/connect-links2Authorization: Bearer pk_live_…3 4{5  "key": "customer_42",6  "platform": "linkedin",7  "redirectUrl": "https://yourapp.com/connected"8}
Field Meaning
key The scoped key the new account will be attached to.
platform The network to connect, for example linkedin or x.
redirectUrl Where your client lands after they finish.
Responsejson
1{2  "url": "https://connect.postkey.dev/c/…",3  "expiresAt": "2026-12-01T10:00:00Z"4}

Send your client to url. How long a link stays valid: details before launch.

When the client finishes

Postkey sends this webhook to your endpoint:

account.connectedjson
1{2  "type": "account.connected",3  "key": "customer_42",4  "account": "acc_li_456",5  "platform": "linkedin"6}

From then on, the key customer_42 can post to acc_li_456.

Many clients? Make one key per client and one connect link per network they use. Each client's accounts end up on their own key, so one client's key can never reach another client's accounts.

Scoped keys and permissions

A scoped key belongs to one customer, workflow or AI agent. It can only post to the accounts listed on it, within the limits you set. You manage keys with your account secret. More on the scoped keys page.

Create a key

Requesthttp
1POST /v1/keys2Authorization: Bearer pk_live_…3 4{5  "name": "customer_42",6  "accounts": [7    "acc_ig_123",8    "acc_li_456",9    "acc_x_789"10  ],11  "dailyPostLimit": 20,12  "monthlySpendLimit": 1513}
Field Meaning
name Your name for the key, usually your customer or agent ID. It shows up in the activity log and is used to change the key later.
accounts The connected account IDs this key may post to. Nothing else is reachable with it.
dailyPostLimit Optional. Most posts this key can send per day.
monthlySpendLimit Optional. A spend cap for this key per month. Units: details before launch.

The response includes the key's secret. Give that secret to the customer or agent.

A key only reaches its own accounts

If a key tries to post to an account that isn't listed on it, for example another customer's account, the post is refused and nothing reaches the network:

Requesthttp
1POST /v1/posts2Authorization: Bearer pk_cust_42_…3 4{5  "content": "Hello from customer 42",6  "accounts": [7    "acc_x_901"8  ]9}
403 · blockedjson
1{2  "status": "blocked",3  "reason": "account_not_allowed",4  "message": "acc_x_901 isn't one of customer_42's accounts."5}

Change limits

Limits live on the key and can only be changed with the account secret. A customer or agent holding the key can't raise them.

Requesthttp
1PATCH /v1/keys/agent_scheduler2Authorization: Bearer pk_live_…3 4{5  "dailyPostLimit": 506}

Kill switch

Turn one key off. Only that key stops, including its scheduled posts. Every other key keeps working.

Requesthttp
1PATCH /v1/keys/agent_scheduler2Authorization: Bearer pk_live_…3 4{5  "active": false6}

Posts from a disabled key come back blocked with key_inactive. Set active back to true to turn it on again with the same limits and history.

Publishing

One endpoint posts to every network: POST /v1/posts. Call it with a scoped key. The examples below use customer_42's key, which has their Instagram, LinkedIn and X accounts on it.

Post now

Requesthttp
1POST /v1/posts2Authorization: Bearer pk_cust_42_…3 4{5  "content": "We just shipped dark mode",6  "accounts": [7    "acc_ig_123",8    "acc_li_456",9    "acc_x_789"10  ],11  "media": [12    {13      "type": "image",14      "url": "https://cdn.example.com/dark-mode.png"15    }16  ]17}
Field Meaning
content The text of the post.
accounts Connected account IDs to post to. They can be on different networks.
media Optional. A list of { type, url }, where type is image, video or document.
scheduledFor Optional. An ISO 8601 time. See Schedule a post.
instagram, linkedin, x, … Optional. Options that only one network has, under that network's name.
200 · publishedjson
1{2  "id": "post_8f21c",3  "status": "published",4  "results": [5    {6      "account": "acc_ig_123",7      "platform": "instagram",8      "status": "published",9      "url": "https://www.instagram.com/p/…"10    },11    {12      "account": "acc_li_456",13      "platform": "linkedin",14      "status": "published",15      "url": "https://www.linkedin.com/feed/update/…"16    },17    {18      "account": "acc_x_789",19      "platform": "x",20      "status": "published",21      "url": "https://x.com/acme/status/…"22    }23  ]24}

One result per network

Every account in accounts gets its own entry in results, with its own status and, once live, a url. If one network fails, the others still go out, and the failed one says why. Results that finish later (video processing, scheduled posts) also arrive by webhook.

Platform options

Anything only one network has sits under that network's key. The rest of the request stays the same. Here the Instagram account gets a Reel and X gets a normal post with the same video:

Requesthttp
1POST /v1/posts2Authorization: Bearer pk_cust_42_…3 4{5  "content": "Dark mode, 20 seconds",6  "accounts": [7    "acc_ig_123",8    "acc_x_789"9  ],10  "media": [11    {12      "type": "video",13      "url": "https://cdn.example.com/dark-mode.mp4"14    }15  ],16  "instagram": {17    "format": "reel",18    "shareToFeed": true19  }20}

Each network's options and limits are on its own page, for example the Instagram posting API and the LinkedIn posting API.

Schedule a post

Add scheduledFor to any post. It's checked now and published at that time.

Requesthttp
1POST /v1/posts2Authorization: Bearer pk_cust_42_…3 4{5  "content": "Doors open at 9. See you there.",6  "accounts": [7    "acc_ig_123",8    "acc_li_456",9    "acc_x_789"10  ],11  "media": [12    {13      "type": "image",14      "url": "https://cdn.example.com/launch.png"15    }16  ],17  "scheduledFor": "2026-12-01T09:00:00Z"18}
202 · scheduledjson
1{2  "id": "post_4d7a1",3  "status": "scheduled",4  "scheduledFor": "2026-12-01T09:00:00Z",5  "results": [6    {7      "account": "acc_ig_123",8      "platform": "instagram",9      "status": "queued"10    },11    {12      "account": "acc_li_456",13      "platform": "linkedin",14      "status": "queued"15    },16    {17      "account": "acc_x_789",18      "platform": "x",19      "status": "queued"20    }21  ]22}

Scheduled posts can be moved or cancelled until they go out. The exact calls for that, and how far ahead you can schedule: details before launch.

Statuses

The post as a whole (status on the response):

Status Meaning
published Live on every network in the request.
processing At least one network is still processing media. Final results come by webhook.
scheduled Queued for scheduledFor.
blocked Refused before anything was sent. See Guardrails.

Each entry in results:

Status Meaning
published Live on that network. url links to it.
processing The network is still processing it, usually video.
queued Waiting for its scheduled time.
failed That network refused it. A webhook says why and whether a retry can help.

Guardrails and blocked responses

Postkey checks every post against the key's rules before anything reaches a network. If a rule says no, you get status: "blocked" with a reason and a plain message. Nothing is posted. More on the limits page.

Reasons

Reason What it means
daily_limit_reached The key hit its dailyPostLimit for today.
monthly_spend_limit_reached The key hit its monthlySpendLimit for this month.
duplicate_blocked The same content already went to that account recently.
account_not_allowed The account isn't listed on this key.
key_inactive The key was turned off with the kill switch.

How long the duplicate window is, and the HTTP status for each reason beyond the two shown below: details before launch.

Daily limit

429 · blockedjson
1{2  "status": "blocked",3  "reason": "daily_limit_reached",4  "message": "customer_42 reached its daily limit (20/20)."5}

Duplicate

blockedjson
1{2  "status": "blocked",3  "reason": "duplicate_blocked",4  "message": "Same content went to acc_x_789 4 minutes ago."5}

Account not on the key

403 · blockedjson
1{2  "status": "blocked",3  "reason": "account_not_allowed",4  "message": "acc_x_901 isn't one of customer_42's accounts."5}

Failed posts don't count toward a key's limits. Only posts that went out count.

Activity log

Every post, refusal and failure is logged under the key that caused it. Read it with your account secret. More on the activity log page.

Requesthttp
1GET /v1/logs?key=agent_scheduler2Authorization: Bearer pk_live_…
200json
1[2  {3    "at": "2026-11-17T03:12:04Z",4    "key": "agent_scheduler",5    "event": "post.blocked",6    "platform": "x",7    "reason": "duplicate_blocked"8  },9  {10    "at": "2026-11-17T03:08:51Z",11    "key": "agent_scheduler",12    "event": "post.published",13    "platform": "x"14  },15  {16    "at": "2026-11-16T22:30:00Z",17    "key": "agent_scheduler",18    "event": "post.scheduled",19    "platform": "linkedin"20  },21  {22    "at": "2026-11-16T21:02:17Z",23    "key": "agent_scheduler",24    "event": "post.published",25    "platform": "instagram"26  }27]
Field Meaning
at When it happened, in UTC.
key The key that did it.
event post.published, post.scheduled, post.blocked or post.failed.
platform The network.
reason For blocked posts, one of the blocked reasons.

The log can also be filtered by account and time. Parameter names and paging: details before launch.

Webhooks

Postkey sends a webhook to your endpoint for each network a post went to. Immediate results also come back in the API response, so webhooks matter most for video and scheduled posts, which finish later. More on the webhooks page.

Events

Event When
post.published A post went live on one network.
post.failed One network refused a post.
account.connected Proposed. A client finished a connect link.

A failed post

post.failedjson
1{2  "type": "post.failed",3  "postId": "post_8f21c",4  "account": "acc_ig_123",5  "platform": "instagram",6  "status": "failed",7  "reason": "account_not_professional",8  "message": "This is a personal account. Instagram only publishes to Business or Creator accounts.",9  "retryable": false10}

message is written so you can show it to your customer. retryable says whether trying again can help.

Handling events

webhook.jsjs
1app.post("/postkey/webhook", (req, res) => {2  const event = req.body;3  if (event.type === "post.failed" && event.retryable) {4    retryLater(event.postId);5  }6  res.sendStatus(200);7});

Each webhook request is signed so you can check it came from Postkey. The signature header and how to verify it: details before launch.

Platform availability

Every network uses the same request shape. Networks open as each platform approves our app.

Network Key in requests Status
X x At launch
LinkedIn linkedin At launch
Instagram instagram After Meta app review
Facebook facebook After Meta app review
TikTok tiktok After TikTok app review
YouTube youtube Planned
YouTube Shorts youtube Planned
Pinterest pinterest Planned
Google Business googleBusiness Planned

Formats and limits for each network are on its page under the posting API.

Building for many clients?

Walk me through your setup and I'll show you how keys and connect links would fit it.

Book a 15-min call