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:
1https://api.postkey.devSend 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:
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:
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:
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:
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:
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:
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
ProposedThis 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
- Your server asks Postkey for a connect link for one of your keys and one network.
- You send your client to that link. They sign in on the network's own login screen and approve access.
- Postkey runs the OAuth exchange, stores the tokens and keeps them fresh.
- The client lands back on your
redirectUrl. The new account ID is attached to that key, and you get anaccount.connectedwebhook.
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.
Create a connect link
Call this with your account secret.
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. |
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:
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
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:
1POST /v1/posts2Authorization: Bearer pk_cust_42_…3 4{5 "content": "Hello from customer 42",6 "accounts": [7 "acc_x_901"8 ]9}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.
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.
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
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. |
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:
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.
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}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
1{2 "status": "blocked",3 "reason": "daily_limit_reached",4 "message": "customer_42 reached its daily limit (20/20)."5}Duplicate
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
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.
1GET /v1/logs?key=agent_scheduler2Authorization: Bearer pk_live_…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
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
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 |
At launch | |
instagram |
After Meta app review | |
facebook |
After Meta app review | |
| TikTok | tiktok |
After TikTok app review |
| YouTube | youtube |
Planned |
| YouTube Shorts | youtube |
Planned |
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.