What connecting Postiz does#

PilotDeck writes the social copy for your articles. Postiz holds your channel connections and does the posting. Once you connect Postiz, PilotDeck sends each approved post to it, and you release the post from Postiz. The example below uses a PilotDeck site named pilotdeck-testwebsite.

One key, cloud or self-hosted

You give PilotDeck a single Postiz API key. If you run your own Postiz, you also give its public HTTPS address.

Drafts first

Posts land in Postiz as drafts. Nothing publishes until you release it in Postiz.

Reversible

You can disconnect at any time from the same screen. Your Postiz account and channels are not touched.

Before you start#

You need	Details
A Postiz account	Either Postiz Cloud or your own Postiz instance, with at least one channel connected. Postiz calls a connected social account a channel.
A public HTTPS address (self-hosted only)	The address you open Postiz at, for example `https://postiz.example.com`. A LAN or localhost address cannot be connected. Put the instance behind a public HTTPS reverse proxy first.
A PilotDeck login	Permission to change integrations for the site. Without it the tools section is unavailable or its buttons are disabled.

Treat the key like a password. Anyone who has it can create and delete posts in your Postiz account. Never paste it into chat, tickets or screenshots. PilotDeck checks it before saving and stores it encrypted. Every credential in this guide is masked.

Postiz Cloud has no free plan. Postiz's documentation says a Cloud organisation cannot use the app until it picks a plan, and new organisations are normally offered a 7 day trial. Self-hosting has no plans or limits. Check which one you use before you start.

Overview#

1Connect at least one channel in PostizYou
2Open Settings > Public API in Postiz and create an API keyYou
3Open Settings > Integrations in PilotDeck and pick Postiz under Shares what you publishYou
4Paste the key, add your Instance URL if you self-host, then click ConnectYou
5Check the key by listing your Postiz channels, then save itPilotDeck
6Choose which accounts this site publishes toYou
7Click Test and confirm the account countVerify

Connect a channel in Postiz#

You

PilotDeck can only post to channels that already exist in Postiz. In the left sidebar of the calendar, click Add Channel, pick a platform and follow its prompt. Depending on the platform that is an OAuth screen, a credentials form or an instance URL prompt. A channel with a red marker needs to be reconnected.

Illustration of the Postiz calendar with an Add Channel button and a grid of platforms — Illustration, based on Postiz's public documentation: click Add Channel and choose a platform.

Create an API key in Postiz#

You

Illustration of the Postiz Settings, Public API page showing an API key with a copy button — Illustration: the key belongs under Settings > Public API. The value shown is a placeholder.

Postiz takes the key on its own in the Authorization header, with no Bearer prefix. PilotDeck sends it that way for you.

Copy it before you leave the page. Keep it somewhere private until you have pasted it into PilotDeck. If you lose it, create a new one in the same place.

Open Integrations in PilotDeck#

You

In PilotDeck, make sure the correct site is selected in the top-left site switcher (here, pilotdeck-testwebsite). Go to Settings > Integrations and find the Shares what you publish section. It reads "Connect the scheduling tool you already use. Posts land there as drafts for you to release."

Under Connect a tool, click the Postiz tile. It is marked API key and shows a Not connected badge. A "How to connect Postiz" panel opens next to a Your details form.

Paste the key and connect#

You

PilotDeck Postiz form with an API key, Instance URL and label — The Your details form. The key is hidden, and the address and label are examples.

Paste the key into Postiz API Key (required). The field shows dots, so you can't read it back. In this guide the value is <your-postiz-api-key>.
Self-hosting? Enter the public HTTPS address in Instance URL, for example https://postiz.example.com, with no path. Leave it blank for Postiz Cloud.
Optionally enter a Label (optional), such as "Marketing workspace". It is shown on the card.
Click Connect.

The Connect button stays disabled until the key is filled in.

How the Instance URL is checked. For a self-hosted address, PilotDeck refuses anything that is not public HTTPS, including loopback, link-local and private network addresses. It saves the cleaned address, not the exact text you typed.

PilotDeck checks the key#

PilotDeck

Before anything is saved, PilotDeck asks Postiz for your list of channels with the key you pasted. If that works, the key is stored encrypted and the channels are saved with the connection. If it fails, nothing is saved and you see the error (see Troubleshooting).

A Postiz card appears under Your tools with a Connected badge. If you set an Instance URL, it shows under the name. Below that, your channels are grouped by network, for example "LinkedIn x1" or "Facebook x3". If Postiz has no channels yet, the card says "No accounts found in this tool yet."

Choose the accounts this site uses#

You

Scroll to Which accounts does this site use? Posts for this site publish only to the accounts you select here, not to every account Postiz has. Each account appears as a tile under its network, with a line such as "LinkedIn, via Postiz".

Click the tiles of the accounts this site should post to.
Click Save Changes. A Saved. note appears next to the button.
Click Cancel instead to drop an unsaved selection.

If a site has no accounts selected for a platform, PilotDeck does not fall back to all your channels. It reports "This site has no social accounts configured for this platform yet. Pick accounts in Settings > Integrations."

Test the connection#

Verify

On the Postiz card, click Test. PilotDeck asks Postiz for your channels again. A pass reads "Key works, 3 accounts found." with your own count. A failure shows the reason in the card and changes the badge (see Statuses).

Done. Approved social posts for this site now go to Postiz as drafts, for the accounts you selected.

How posts reach Postiz#

PilotDeck sends a post to Postiz as a draft unless the post is already approved and a send is explicitly requested as not a draft. A draft has no publish time. You open Postiz, review it and release it there. After a draft is sent, the post leaves the PilotDeck queue as scheduled, and Postiz keeps the draft state.

Item	What PilotDeck supports
Networks	LinkedIn (profile and page), Facebook, Instagram (including standalone), X and Threads. Postiz channels for other networks are listed on the card, but PilotDeck writes copy only for these five.
Post types	Text posts, with an optional link appended, and image carousels of 2 to 10 slides. Images are uploaded to Postiz with the post.
One send, many channels	A single send can target several of your selected channels.
Ready to send	Only approved posts or ready drafts can be sent to your tool. Review the post first.

Statuses#

Badge	Meaning	What to do
Connected	The last check of the key worked.	Nothing.
Needs re-auth	Postiz rejected the key or said it expired during a test or a channel refresh.	Create a new key in Postiz, then disconnect and connect again.
Error	Any other failure, such as Postiz being unreachable. The reason shows in red on the card.	Fix the cause, then click Test.
Not connected	On the Postiz tile: no connection exists for this site.	Follow the steps above.

Limits#

Postiz limits how many posts you can create per hour: 100 on Postiz Cloud. A self-hosted instance using the shipped docker-compose allows 30. If you hit the limit, PilotDeck shows "Your social tool is limiting requests right now. Wait a few minutes and try again."
A self-hosted instance must be reachable over public HTTPS. The Docker default http://localhost:4007 cannot be connected.
The key goes in Postiz's authorization header on its own, with no "Bearer" prefix. PilotDeck does this for you.

Disconnecting#

On the Postiz card click Disconnect and confirm the prompt "Disconnect Postiz? Queued posts for its platforms will need a tool again." Only this site's connection is removed. To fully remove access, also delete the key in Postiz under Settings > Public API.

To use a new key, disconnect first, then click the Postiz tile again and repeat steps 3 and 4. If you connect again without disconnecting, the saved key is replaced and the accounts are refreshed.

Troubleshooting#

"Enter your API key to connect this social tool."

The Postiz API Key field was empty. Paste the key and click Connect again.

"Your social tool rejected the API key. Check the key and reconnect."

Postiz did not accept the key. Check that you copied all of it with no spaces, that it comes from the same Postiz you entered (cloud or your own instance), and that it was not deleted.

Connect fails for my self-hosted address

Use the public HTTPS address you open Postiz at, with no path and no /api. Loopback, LAN and plain HTTP addresses are refused. Put the instance behind a public HTTPS reverse proxy.

"Your social tool did not accept this request. Check your connection details and try again."

Postiz refused the request. For a send, the usual causes are a carousel with fewer than 2 or more than 10 slides, or a channel Postiz no longer has. Reconnect to refresh the channel list.

"None of your connected social tools has a channel for this platform."

Connect a channel for that network in Postiz, then click Test in PilotDeck to refresh the account list.

"Only approved posts or ready drafts can be sent to your social tool."

Review and approve the post in PilotDeck first, then send it again.

"We couldn't confirm whether this reached your social tool before the connection timed out."

The request may have reached Postiz before the reply was lost. Look in Postiz for the draft before you send again, to avoid a duplicate.

"One of the images in this carousel could not be loaded."

Re-attach the images to the carousel in PilotDeck and try again.

Nothing was posted live

This is expected. Posts arrive in Postiz as drafts. Open Postiz and release them there.