v1.1.0REST · JSON · bearer key

Planify API

Schedule and publish to 9 social platforms from anything that can make an HTTP request — an AI assistant, a workflow tool, your own script. No browser required.

Get an API key OpenAPI 3.1 spec

Introduction

Planify schedules and publishes social posts. This API exists so software can do that — an AI assistant acting for a person, a workflow in n8n or Zapier, or a script you wrote yourself.

Every response is JSON. Every error uses one envelope. Field names are snake_case throughout, including the platform settings, so nothing changes case halfway through a request.

Base URL

https://planifyapps.com/api/v1

Auth

Authorization: Bearer <key>

Spec

/openapi.json

MCP server

npx -y @planifyapps/mcp

Publish a post in five calls

Step 2 is the one worth not skipping. It reports the character limit, media rules and required settings for that specific channel — which is the difference between a post that publishes and one that discovers each rule by being rejected.

bash

export PLANIFY_API_KEY="plfy_live_..."
API="https://planifyapps.com/api/v1"

# 1 · find a channel
curl -s "$API/channels" -H "Authorization: Bearer $PLANIFY_API_KEY"

# 2 · learn what it accepts — limits, rules, settings schema, lookups
curl -s "$API/channels/$CHANNEL_ID/settings" -H "Authorization: Bearer $PLANIFY_API_KEY"

# 3 · fetch anything unguessable, e.g. a Pinterest board
curl -s -X POST "$API/channels/$CHANNEL_ID/trigger" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method_name":"boards"}'

# 4 · get an image in (the server downloads it for you)
curl -s -X POST "$API/media/from-url" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/photo.jpg"}'

# 5 · publish
curl -s -X POST "$API/posts" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"now","content":"Shipped something today.","channel_ids":["'"$CHANNEL_ID"'"]}'

Authentication

Send an API key as a bearer token. Create one in the dashboard under Settings → API.

Keys are shown exactly once and stored only as a SHA-256 hash, so a lost key is replaced rather than recovered — and a database leak cannot be replayed against the API. Keys cannot create other keys, so a leaked key cannot mint more.

http

Authorization: Bearer plfy_live_b5Ihj_NPiuEWh5BQrAz5wAHLmW8mi…

Scopes

A key carries only the scopes it was created with. Notably posts:publish is not granted by default — so a leaked read-write key can prepare drafts but cannot post to your audience.

If you are wiring up an AI assistant and want it to prepare work for your approval rather than publish on its own, issue a key without that scope and everything else still works.

Available scopes

channels:read	default	List channels, read their posting rules, and run their lookups.
posts:read	default	Read posts that already exist.
posts:write	default	Create drafts and scheduled posts.
posts:publish	opt-in	Publish immediately. Never granted by default — ask for it explicitly.
media:write	default	Upload images and video.
analytics:read	default	Read performance data.

Rate limits

Counted per key, per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also carries Retry-After.

Publishing is tightest because it is the one action that cannot be undone.

120

read / min

write / min

publish / min

Idempotency

Send an Idempotency-Key header on POST /v1/posts wherever a retry is possible. Repeating a request with the same key returns the posts created the first time rather than creating more, and sets idempotent_replay: true.

This matters more for software than for people, because software retries automatically. Generate one key per intended post — a UUID is ideal — and reuse it across retries of that same post.

Errors

Every failure returns the same envelope. Branch on code — it is stable and machine-readable. hint usually names the endpoint that answers the question.

json

{
  "error": {
    "code": "validation_failed",
    "message": "twitter (channel ch_1a2b3c): Content exceeds Twitter limit of 280 characters",
    "hint": "GET /api/v1/channels/:id/settings returns the limits and rules for each channel."
  }
}

Status codes you should handle

401	invalid_api_key	Missing, unrecognised or revoked key. Do not retry.
402	payment_required	The plan does not include this. GET /v1/me reports plan and status.
403	insufficient_scope	The key lacks a needed scope. Do not retry with this key.
409	request_in_progress	An identical Idempotency-Key request is still running. Wait and retry.
422	validation_failed	The post breaks a channel rule. Read the channel settings.
429	rate_limited	Honour Retry-After.
502	platform_error	The social platform refused it. Retrying may help.

Account

get/v1/me

Who this credential is, and what it may do

The first call to make. Reports the plan, the scopes the key carries, and quota remaining.

Deliberately answers even when the plan grants no app access — it is how a caller discovers it is paywalled, rather than inferring that from a 402 somewhere less obvious.

Scopes: none beyond a valid credential.

Rate class: read (120/min)

curl

curl -s "https://planifyapps.com/api/v1/me" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

user_id	string (uuid)	—
auth	object	—
endpoints	object	All 20 endpoints, split by whether this credential can call them. The scopes a key holds only answer the question if you already know which scope each endpoint wants — so the mapping is served, and `denied` names the missing scope per entry. A key without posts:publish can prepare and schedule everything and publish nothing; saying so up front beats failing the call. A cookie session holds every scope, so denied is empty.
plan	object	—
platforms	string[]	Platforms this plan may publish to. A channel outside this list is read-only.
features	object	—
usage	object	A null limit means unlimited, and so does a null remaining.
rate_limits	object	Per-minute ceilings by operation weight, so a client can pace itself.

Channels

get/v1/channels

List connected channels

Channels the credential can reach. "Channel" rather than "account" because that word already means the Planify user, the social login, and the individual Facebook Page.

Channels the plan excludes are returned with available: false rather than hidden — omitting them would be indistinguishable from the account never having been connected.

Scopes: channels:read

Rate class: read (120/min)

curl

curl -s "https://planifyapps.com/api/v1/channels" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

channels	object[]	—
summary	object	—

get/v1/channels/{id}/settings

What this channel will accept — the endpoint to read before writing a post

Character and media limits, the hard rules that decide whether a publish succeeds, a JSON Schema for this platform's slice of platform_settings, and the lookups this channel supports.

Reading this first is the difference between a post that publishes and one that discovers each rule by being rejected. The settings schema is generated from the types the publishing code actually reads, so it cannot go stale.

Scopes: channels:read

Rate class: read (120/min)

Parameters

idrequired

string

Channel id from GET /v1/channels.

curl

curl -s "https://planifyapps.com/api/v1/channels/$CHANNEL_ID/settings" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

id	string (uuid)	—
platform	string	—
username	string \| null	—
display_name	string \| null	—
available	boolean	—
unavailable_reason	string	—
limits	object	—
media	object	How attachments are treated, beyond the counts in limits.
threading	object	—
rules	string[]	Hard requirements first, then style guidance. Prose, written to be read by a model.
settings_schema	object \| null	JSON Schema for this platform's slice of platform_settings.
tools	object[]	—

post/v1/channels/{id}/trigger

Run a per-channel lookup

Some platforms need a value that cannot be guessed. Pinterest rejects a pin without board_id, and that id is opaque — so without this an agent cannot post to Pinterest at all.

Which lookups a channel supports is advertised as tools by GET /v1/channels/{id}/settings, so they are discovered rather than hardcoded. POST rather than GET because the arguments are structured and some lookups hit a rate-limited upstream API.

Scopes: channels:read

Rate class: read (120/min)

Parameters

idrequired

string

Channel id.

Body — application/json

method_name	string	Which lookup to run. Listed as tools[].method_name by GET /v1/channels/:id/settings.
methodName	string	—
data	object	Arguments for the lookup, matching that tool's input schema.

curl

curl -s -X POST "https://planifyapps.com/api/v1/channels/$CHANNEL_ID/trigger" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method_name": "boards" }'

Response — 200

method_name

string

—

get/v1/channels/{id}/slot

Next free posting slot for a channel

An agent told to "post this sometime good" has no way to pick a time. The user has usually already answered that in the dashboard as a weekly schedule; this is how that answer reaches the agent.

Slots already taken by a scheduled post are skipped, so filling a week does not stack everything on one time. Returns slot: null with a reason when the channel has no schedule — that is not an error.

Scopes: channels:read

Rate class: read (120/min)

Parameters

idrequired	string	Channel id.
?count	integer	How many slots to return.
?after	string (date-time)	Search from a later point than now.

curl

curl -s "https://planifyapps.com/api/v1/channels/$CHANNEL_ID/slot" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

channel_id	string (uuid)	—
platform	string	—
schedule	object \| null	The weekly schedule these came from, or null when none is set.
slots	string (date-time)[]	Ascending, UTC.
slot	string \| null	First of slots — what most callers want.
reason	string	Present when there are no slots to give.
note	string	Present when fewer slots were free than requested.

get/v1/channels/{id}/schedule

Read a channel's weekly posting schedule

The slots and the timezone they are written in.

Returns schedule: null for a channel that has none, which is also why GET /channels/{id}/slot would return slot: null. Null rather than a 404, because a 404 reads as "no such channel".

Scopes: channels:read

Rate class: read (120/min)

Parameters

idrequired

string

Channel id from GET /v1/channels.

curl

curl -s "https://planifyapps.com/api/v1/channels/$CHANNEL_ID/schedule" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

channel_id	string (uuid)	—
platform	string	—
schedule	object \| null	Null when this channel has no schedule — the common case, and not an error.
reason	string	Present when schedule is null.
next_slot_endpoint	string	Where the schedule turns into timestamps.

put/v1/channels/{id}/schedule

Set a channel's weekly posting schedule

Replaces the whole schedule — send every slot you want, not just the new ones.

Times are local wall-clock time in `timezone`, never UTC. That is what makes "Tuesdays at 12:30" survive a daylight-saving change: the slot is stored as 12:30 in a named zone and converted to UTC each time a post is scheduled, so it stays 12:30 to the audience rather than drifting by an hour twice a year. Storing UTC times, or offsets, is the bug this shape avoids.

The zone is validated against the runtime tz database, not a regex: "Asia/Calcutta" and "Asia/Kolkata" are both real, "Asia/Bangalore" is not, and a typo that stores cleanly surfaces weeks later as posts going out at the wrong hour.

Writes the same table and the same { day, time } shape the dashboard editor uses, so a schedule set here is editable in the UI and the other way round. Duplicate slots are dropped. An empty slots array clears the schedule.

Scopes: channels:read, posts:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Parameters

idrequired

string

Channel id from GET /v1/channels.

Body — application/json

timezonerequired	string	IANA zone the slots are written in, e.g. "Asia/Kolkata". Slots are local to it and converted to UTC when a post is scheduled, so a slot survives a daylight-saving shift.
slotsrequired	object[]	The weekly grid. An empty array clears the schedule without deleting the row.

curl

curl -s -X PUT "https://planifyapps.com/api/v1/channels/$CHANNEL_ID/schedule" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

channel_id	string (uuid)	—
platform	string	—
schedule	object \| null	Null when this channel has no schedule — the common case, and not an error.
reason	string	Present when schedule is null.
next_slot_endpoint	string	Where the schedule turns into timestamps.

delete/v1/channels/{id}/schedule

Remove a channel's posting schedule

Removes the weekly template. Posts already scheduled at those times keep their times — this stops future slot suggestions, it does not unschedule anything.

Scopes: channels:read, posts:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Parameters

idrequired

string

Channel id from GET /v1/channels.

curl

curl -s -X DELETE "https://planifyapps.com/api/v1/channels/$CHANNEL_ID/schedule" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

deleted	boolean	—
channel_id	string (uuid)	—
note	string	—

Media

get/v1/media

List uploaded media

The account's media, newest first.

Lists the storage folder rather than a table, which means it returns files uploaded through the web app as well as through the API — the case that matters is an agent finishing a post a person started, where the images are already in Planify and the agent just needs to name them.

media:write rather than a read scope because there is no media:read, and these are exactly the files that scope creates. Adding a scope would break every key already issued.

Scopes: media:write

Rate class: read (120/min)

Parameters

?limit	integer	Items per page.
?offset	integer	From next_offset on the previous page.
?mime_type	string	Prefix match on content type, e.g. "image/". Narrows this page only — Storage has no server-side filter, so a page can come back short while later pages still hold matches.

curl

curl -s "https://planifyapps.com/api/v1/media" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

media	object[]	—
next_offset	integer \| null	Pass as ?offset= for the next page. Null means this was the last.
note	string	Present when mime_type was used.

post/v1/media

Upload one or more files

multipart/form-data with one or more file parts. Multipart rather than base64 JSON because a 100MB video base64-encodes to ~133MB of request body, and every HTTP client already knows how to do this.

Returns public URLs to pass as media_urls when creating a post.

Scopes: media:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Body — multipart/form-data

file

file[]

Up to 10 files, each at most 100MB.

curl

curl -s -X POST "https://planifyapps.com/api/v1/media" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -F "file=@photo.jpg"

Response — 200

media	object[]	—
media_urls	string (uri)[]	Exactly what media_urls on POST /v1/posts expects, so one call feeds the next.

post/v1/media/from-url

Have the server download media from a URL

The common agent shape: an image was just generated somewhere and exists only as a URL, so making the agent download and re-upload it is pure round trip.

Every URL is resolved and checked before any request leaves the server, and again on each redirect hop — private, loopback, link-local and cloud-metadata addresses are refused.

Scopes: media:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Body — application/json

url	string	A single publicly reachable URL to ingest.
urls	string[]	Several URLs to ingest in one call.

curl

curl -s -X POST "https://planifyapps.com/api/v1/media/from-url" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/photo.jpg" }'

Response — 200

media	object[]	—
media_urls	string (uri)[]	Exactly what media_urls on POST /v1/posts expects, so one call feeds the next.

Posts

post/v1/posts/validate

Check a post without creating it

The same body as POST /v1/posts, checked and discarded. Nothing is created, nothing is published.

GET /v1/channels/{id}/settings already returns the rules, and a caller can mostly apply them. Mostly is the problem: it has to count characters the way the server counts them, know that a threaded post is exempt from the character limit, and work out whether a rule has been satisfied. The first time it gets one wrong it finds out by creating something — a draft in someone's queue, or a published post that should not have been.

Runs the create path's own resolution and checking rather than a copy, so a green result here and a rejection there cannot disagree.

A malformed body comes back as 200 with valid: false rather than 400 — the caller asked whether the post is acceptable, and "no, and here is why" is the answer in both cases. An unknown channel id is still a 404: that is a broken request, not an invalid post.

Content and settings only. Plan limits, quotas and the posts:publish scope are checked when the post is created, so valid: true is not a guarantee the create call will succeed. GET /v1/me answers the plan question.

Scopes: posts:read

Rate class: read (120/min)

Body — application/json

type	"draft" \| "schedule" \| "now"	draft saves it, schedule queues it for scheduled_at, now publishes immediately (requires the posts:publish scope).
contentrequired	string \| object[]	A string fans the same copy to every channel in channel_ids. An array gives per-channel copy.
channel_ids	string[]	Required when content is a string; ignored when it is an array.
media_urls	string (uri)[]	Public URLs returned by POST /v1/media or /v1/media/from-url.
media	object[]	Attachments in order, each with optional alt text. Use instead of media_urls, not alongside it.
scheduled_at	string (date-time) \| null	UTC ISO-8601. Required when type is "schedule".
platform_settings	object	Keyed by platform slug: { pinterest: { board_id } }. See GET /v1/channels/:id/settings.
thread	string[]	Post as a thread on platforms that support it. Part one becomes the body.

curl

curl -s -X POST "https://planifyapps.com/api/v1/posts/validate" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

valid	boolean	True when nothing fatal was found.
errors	object[]	Fatal. Each names the field, the rule, and the numbers where there are any.
warnings	string[]	Non-fatal: the post would be created, but something in it would be ignored.
channels	object[]	Per channel, because with per-channel copy the answer genuinely differs.
checked	integer	How many channels were checked.
note	string	What a green result does and does not promise.

post/v1/posts

Create a post — draft, scheduled, or published now

content as a string fans the same copy to every channel in channel_ids. As an array of { channel_id, content, … } it gives per-channel copy, which is what you want when the same idea needs 280 characters on Twitter and 2,200 on Instagram.

type: "now" publishes immediately and requires the posts:publish scope, which keys do not carry unless asked for — so a leaked read-write key cannot post to someone's audience.

Attachments. media_urls and media both work; media is the form that carries alt text, as [{ url, alt }]. Prefer it when the images carry information — for a data slide the alt text is the only machine-readable copy of the numbers on it, and there is no other way to attach it to a scheduled post. Where both are sent, media wins. limits.supports_alt_text on GET /v1/channels/{id}/settings says whether a given channel delivers it.

Order is the post's order. Index 0 is the first attachment, and for an Instagram carousel that is the first slide — the services iterate the array as given, so reordering it reorders the post.

POST /v1/posts/validate takes this same body and reports what would happen, without creating anything.

Send an Idempotency-Key header wherever a retry is possible. Repeating a request with the same key returns the original posts instead of creating more, and sets idempotent_replay: true.

Scopes: posts:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Parameters

Idempotency-Key

string

Makes the call replay-safe. Send one wherever a retry is possible.

Body — application/json

type	"draft" \| "schedule" \| "now"	draft saves it, schedule queues it for scheduled_at, now publishes immediately (requires the posts:publish scope).
contentrequired	string \| object[]	A string fans the same copy to every channel in channel_ids. An array gives per-channel copy.
channel_ids	string[]	Required when content is a string; ignored when it is an array.
media_urls	string (uri)[]	Public URLs returned by POST /v1/media or /v1/media/from-url.
media	object[]	Attachments in order, each with optional alt text. Use instead of media_urls, not alongside it.
scheduled_at	string (date-time) \| null	UTC ISO-8601. Required when type is "schedule".
platform_settings	object	Keyed by platform slug: { pinterest: { board_id } }. See GET /v1/channels/:id/settings.
thread	string[]	Post as a thread on platforms that support it. Part one becomes the body.
idempotency_key	string	In-body equivalent of the Idempotency-Key header; the header wins.

curl

curl -s -X POST "https://planifyapps.com/api/v1/posts" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
     "type": "schedule",
     "content": "Shipped the thing. Notes in the thread.",
     "channel_ids": ["ch_1a2b3c"],
     "media_urls": ["https://…/photo.jpg"],
     "scheduled_at": "2026-08-04T09:30:00Z"
  }'

Response — 200

type	"draft" \| "schedule" \| "now"	—
posts	object[]	—
warnings	string[]	Non-fatal. E.g. a thread sent to a platform that does not support threading.
idempotent_replay	boolean	True when this Idempotency-Key had already been used and nothing new was created.
publish	object	Present only for type "now".

get/v1/posts

List posts in a date range

"What is already scheduled this week" is the question that comes before "add another", so the date window is the primary filter rather than an afterthought.

The window filters on scheduled_at, which means undated drafts are excluded — a date-range question is about the calendar, and an undated draft is not on it. Omit from and to to see everything, newest first.

Scopes: posts:read

Rate class: read (120/min)

Parameters

?from	string (date-time)	Start of the window (inclusive), ISO-8601.
?to	string (date-time)	End of the window (inclusive), ISO-8601.
?status	"draft" \| "scheduled" \| "published" \| "failed" \| "partial"	Filter by status.
?channel_id	string	Only posts targeting this channel.
?platform	string	Only posts targeting this platform.
?limit	integer	Rows to return.

curl

curl -s "https://planifyapps.com/api/v1/posts" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

posts	object[]	—
total	integer	Total matching the filters, ignoring limit.
note	string	Present when the result was truncated by limit.

get/v1/posts/{id}

Read one post

The full stored post, including its platform settings and publish status.

Scopes: posts:read

Rate class: read (120/min)

Parameters

idrequired

string

Post id.

curl

curl -s "https://planifyapps.com/api/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

post

object

—

patch/v1/posts/{id}

Edit a draft or scheduled post

Change the content, media, settings, schedule, or flip between draft and scheduled. Everything is optional; send only what changes.

A published post cannot be edited (409). A published row records something that exists on a real platform, and changing it would make Planify disagree with what the audience actually saw. Editing the live post is a different operation with different per-platform limits, and pretending a PATCH does that would be worse than refusing.

The result is validated against the target channel exactly as creation is, so an edit cannot push a post past a character limit.

Sending media replaces the attachments and their alt text together, and media_urls clears the alt text along with them — leaving old descriptions attached to new images would describe the wrong pictures.

Scopes: posts:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Parameters

idrequired

string

Post id.

Body — application/json

content	string	—
media_urls	string (uri)[]	Replaces the attachments, and clears any alt text they had.
media	object[]	Replaces the attachments and their alt text together. Use this when any has alt text.
status	"draft" \| "scheduled"	Flip between the two. Cannot be set to published — publish it instead.
scheduled_at	string \| null	Required when status is scheduled.
platform_settings	object	—

curl

curl -s -X PATCH "https://planifyapps.com/api/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $PLANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Reworded before it goes out.", "status": "scheduled", "scheduled_at": "2026-08-05T09:00:00Z" }'

Response — 200

post

object

—

delete/v1/posts/{id}

Delete a post

Removes the post from Planify.

Deleting an already-published post is allowed but removes only Planify's record — the post stays live on the platform and must be removed there. The response says so explicitly, because an agent asking to "delete the post" quite likely meant to unpublish it.

Scopes: posts:write

Rate class: write (60/min)

Requires an active subscription (402 otherwise).

Parameters

idrequired

string

Post id.

curl

curl -s -X DELETE "https://planifyapps.com/api/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

deleted	boolean	—
id	string	—
note	string	Present when the deleted post had already been published.

post/v1/posts/{id}/publish

Publish a post that already exists

Publishes a draft or scheduled post now. POST /v1/posts with type: "now" covers create-and-publish; this covers a post prepared earlier and since approved.

That approval flow is the point. Issue an agent a key with posts:write but not posts:publish and it can prepare everything and publish nothing — a human then calls this. Without it, "let the agent draft and I will approve" would mean approving in the dashboard only.

Returns a per-channel result. Republishing an already-published post is refused with 409 rather than posting a duplicate to the audience.

Scopes: posts:write, posts:publish

Rate class: publish (20/min)

Requires an active subscription (402 otherwise).

Parameters

idrequired

string

Post id.

curl

curl -s -X POST "https://planifyapps.com/api/v1/posts/$POST_ID/publish" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

post_id	string	—
overall_status	"published" \| "partial" \| "failed"	—
results	object[]	—
warning	string	Set when the post published but Planify could not record it. Do not retry.

Analytics

get/v1/analytics

Account performance over a period

Totals and trends across channels. This is what turns a write-only integration into one that can decide: "post three times this week" needs no analytics, "post more of what worked" does.

Requires a plan including analytics — the same gate the dashboard applies, because an API that quietly bypasses a plan feature is a pricing hole rather than a convenience.

Scopes: analytics:read

Rate class: read (120/min)

Parameters

?range	"7d" \| "30d" \| "90d" \| "month" \| "year" \| "lifetime"	Period to report on.
?from	string (date-time)	Custom window start; overrides range.
?to	string (date-time)	Custom window end.
?platform	string	Restrict to one platform.
?channel_id	string	Restrict to one channel.

curl

curl -s "https://planifyapps.com/api/v1/analytics" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

range	string	—
overview	object	Totals, per-platform breakdown and trend series.
note	string	States that figures are synced periodically and may lag the platform.

get/v1/analytics/posts

Per-post performance, sortable

Which posts worked. Sorting is exposed on purpose: "top 10 by engagement over the last 30 days" should be one call, not a full fetch followed by client-side sorting.

Scopes: analytics:read

Rate class: read (120/min)

Parameters

?range	"7d" \| "30d" \| "90d" \| "month" \| "year" \| "lifetime"	Period to report on.
?sort_by	"engagement" \| "likes" \| "shares" \| "comments" \| "reach" \| "impressions" \| "date"	Metric to sort on.
?sort_order	"asc" \| "desc"	Sort direction.
?platform	string	Restrict to one platform.
?channel_id	string	Restrict to one channel.
?limit	integer	Rows to return.
?offset	integer	Rows to skip, for paging.

curl

curl -s "https://planifyapps.com/api/v1/analytics/posts" \
  -H "Authorization: Bearer $PLANIFY_API_KEY"

Response — 200

posts	object[]	—
total	integer	—
next_offset	integer	Present when more rows remain.
note	string	—

Clients

Using Planify from an AI assistant

Planify publishes an MCP server, so an assistant that speaks the Model Context Protocol — Claude, or any other MCP client — can use this API directly without you writing glue code.

claude_desktop_config.json

{
  "mcpServers": {
    "planify": {
      "command": "npx",
      "args": ["-y", "@planifyapps/mcp"],
      "env": { "PLANIFY_API_KEY": "plfy_live_..." }
    }
  }
}

It exposes one tool per endpoint, and the per-channel rules from GET /v1/channels/{id}/settings become the tool inputs — so the assistant is told a channel’s character limit and required fields up front rather than discovering them by being rejected.

The tool that creates posts defaults to a draft. Publishing needs type: "now", a key holding posts:publish, and your confirmation, which the server’s own instructions tell the assistant to ask for.

A note on publishing

Publishing is irreversible and public. If you are building an agent, confirm with the person before publishing on their behalf — draft or schedule first and let them approve. The API supports that path precisely so it can be the default one.

Frequently asked questions

Can an AI assistant post to social media with Planify?

Yes. Planify publishes an MCP server, so any assistant that speaks the Model Context Protocol — Claude among them — can list your connected accounts, read each one's posting rules, upload media and publish. Install it with npx -y @planifyapps/mcp and a Planify API key. Publishing immediately requires a key holding the posts:publish scope, which is withheld by default, so an assistant can prepare drafts without being able to post to your audience.

Which social platforms can the Planify API publish to?

The API can publish to 9 platforms: twitter, facebook, instagram, threads, bluesky, pinterest, mastodon, linkedin, youtube. Which of those a given account may use depends on its plan — GET /api/v1/channels reports availability per channel rather than hiding the ones your plan excludes.

How do I know each platform's character limit and media rules?

Call GET /api/v1/channels/{id}/settings before writing the post. It returns that specific channel's character limit, how much media it accepts, whether media is required, the rules that decide whether publishing succeeds, and a JSON Schema for its platform settings. It is per channel rather than per platform, because a Facebook Page and a personal profile differ.

Does the Planify API prevent duplicate posts on retry?

Yes. Send an Idempotency-Key header on POST /api/v1/posts. Repeating a request with the same key returns the posts created the first time instead of creating more, and sets idempotent_replay: true in the response. This matters more for software than for people, because software retries automatically.

Is there an OpenAPI specification for the Planify API?

Yes, at https://planifyapps.com/openapi.json — OpenAPI 3.1, served without authentication. It is generated from the same schemas the API validates requests against, so it cannot describe a version of the API that no longer exists.

How do I get a Planify API key?

Create one in the Planify dashboard under Settings → API. The key is shown once and stored only as a SHA-256 hash, so a lost key is replaced rather than recovered. Keys cannot create other keys, which means a leaked key cannot mint more.

Ready to build?

Create a key in Settings → API, then start with GET /v1/channels.

Get an API key Talk to us