Connect Postiz to send your Threadgehog posts

Approved posts pile up when there is no time to paste each one into Threads and X by hand. A scheduler does the posting. Connect Postiz with one API key, and Threadgehog hands your approved posts to Postiz, which publishes them to the Threads and X accounts you linked there.

How to set up Postiz

  1. Link Threads and X in Postiz

    Sign up at postiz.com. Every Postiz cloud plan includes the API, and each plan starts with a 7-day free trial. If you run Postiz on your own server, self-hosted installs include the API too. Then, inside Postiz, connect the Threads and X accounts you want to post to. Threadgehog can only send to channels you have linked in Postiz.

  2. Copy your Postiz API key

    In Postiz open Settings > Developers > Public API, click the reveal icon to show the key, then copy it. On Postiz cloud, the "Open Postiz settings" link in Threadgehog opens Postiz's settings page. If you self-host, open the same page on your own Postiz install.

  3. Paste the key into Threadgehog

    In Threadgehog, open Settings > Publishing and click "Connect a scheduler" under "Schedulers". During setup, "How do you want to publish?" opens the same sheet. Under "Pick your scheduler", choose "Postiz" and click "Next". Under "Paste your key", follow the key instructions or click "Open Postiz settings", then paste into "Paste Postiz API key". Set "Scheduled posts your plan allows per channel" to how many posts Threadgehog should keep scheduled per channel at a time; it starts at 10. Postiz plans have no posting cap. On Postiz cloud, leave "Server address (self-hosted only)" empty. If you self-host, enter your backend address (Postiz calls it NEXT_PUBLIC_BACKEND_URL) followed by /public/v1, for example https://postiz.example.com/public/v1. Threadgehog uses the address as typed, apart from dropping a trailing slash, and does not add /public/v1 for you. Threadgehog tests the credentials automatically a moment after you paste them. When it shows "Connected as" followed by the account name, click "Next".

    Paste your key, with Postiz's four setup steps, the Paste Postiz API key and Server address (self-hosted only) fields, Scheduled posts your plan allows per channel: 10, and Test

  4. Choose where the project posts

    The channel step shows a "Threads" picker, an "X" picker, or both, depending on the project. A single matching channel is preselected; if several match, pick one from "Choose channel". If Postiz has no account for a platform, add it in Postiz, then click "Refresh". Click "Done" to save the project's choices. To change a project later, click "Choose" beside it under "Where each project posts" in Settings > Publishing. New projects get a channel automatically when only one matches; with several, choose them under "Where does <project> post?" in the sheet that opens for the new project.

    Where should Potluck Coordinator post?, with Threads set to Postiz · potluckcoordinator and X set to Postiz · @potluckcoord, and the Done button

  5. Pick how often it sends

    In Settings > Publishing, under "Sending", the "Send to Postiz" menu sets how often Threadgehog sends: once a day from 9 AM, twice a day from 9 AM and 5 PM, every 6 hours, or every hour. Threadgehog needs to be open to send; "Send now" in the Queue sends right away. Turn on "Auto-approve X posts" under "X posts" and the X version of each approved Threads post goes straight to the Queue. The Postiz row's "..." menu under "Schedulers" has "Replace key", "Edit", "Test connection" and "Remove". "Edit" opens "Edit Postiz account", where you can change "Label" and the scheduled-posts limit.

    Settings, Publishing: Send to Postiz set to Twice a day, from 9 AM and 5 PM, with Postiz's no-cap note, and the Auto-approve X posts switch

What you get

  • Multi-post threads go to Postiz as real threads on both Threads and X, with each part as its own post.
  • Images upload straight to Postiz, including a different image on each part of a thread, so you do not need a separate media host.
  • Three ways to send: queued posts get a time Threadgehog picks from your posts a day, spread from 9 AM to 9 PM, "Post now" sends one post right away, and "Schedule…" sets an exact time.
  • Threadgehog checks each sent post with Postiz and moves it from Scheduled to Published once Postiz reports it went out. If Postiz reports a failure, the post returns to Pending with a note.
  • On a scheduled post, "Back to pending" and "Delete from Postiz" also ask Postiz to delete its copy.

What it costs

Every Threadgehog plan can send to Postiz, and Threadgehog does not add its own markup or cap for it. Postiz bills you separately for its own plan. As listed on postiz.com/pricing on October 1, 2026, every Postiz cloud plan includes the API and unlimited posts per month: Standard is $29 a month for 5 channels, Team $39 for 10, Pro $49 for 30 and Ultimate $99 for 100 when billed monthly, or $23, $31, $39 and $79 a month billed yearly. Each plan starts with a 7-day free trial. Self-hosted Postiz is open source (AGPL-3.0) with no Postiz subscription; you pay for the server you run it on. Prices can change, so check postiz.com/pricing before you sign up.

Your key and your data

Threadgehog keeps your Postiz key in your Mac's Keychain and does not write it to its settings file. Publishing requests go from your Mac straight to Postiz at api.postiz.com, or to the server address you entered, so the key and those requests never pass through Threadgehog's servers. Each connected scheduler account keeps its own Keychain entry, so connecting another account, for Postiz or any other scheduler, never overwrites or breaks this one. There is no separate sign-in screen to approve: the key alone connects Threadgehog to your Postiz account. To cut off access, rotate the key in Postiz under Settings, Developers, Public API. Postiz says rotating stops the old key from working right away, so reconnect Threadgehog with the new key using the steps under "Postiz rejected this key" below.

Limits to know

  • Threadgehog needs to be open to send. While it is closed, approved posts wait in the queue.
  • You choose how often Threadgehog sends in Settings, Publishing: once a day from 9 AM, twice a day from 9 AM and 5 PM, every 6 hours, or every hour.
  • Threadgehog keeps up to the number you set per channel in Postiz at a time (the "Scheduled posts your plan allows per channel" stepper, 1 to 5000, default 10; change it with "Edit" in the account row's "..." menu under "Schedulers"). The rest wait in Threadgehog's queue for a later send.
  • Postiz caps create-post requests to its API each hour: 100 on Postiz cloud, and 90 by default on self-hosted installs (Postiz's official docker-compose file sets 30). Threadgehog sends one request per post.
  • Threadgehog lists only Threads and X channels from Postiz and skips any channel that is disabled there.
  • Postiz numbers fill in gradually: Threadgehog reads up to 25 Postiz posts a day for Insights.

Troubleshooting

The channel step says "No Threads account in Postiz yet. Add it in Postiz, then press Refresh." or the same message for X.

Why: The channel list has no Postiz account for that platform. The account may be missing or disabled in Postiz; on a self-hosted install, also check that the server address ends in /public/v1.

Fix: Connect the missing account in Postiz, then click "Refresh" in the channel step, choose it and click "Done". If the saved credentials are wrong, in Settings > Publishing, open the Postiz row's "..." menu under "Schedulers" and choose "Replace key". Paste the current key into "New API key". Check "Server address" too if you self-host. Click "Replace"; Threadgehog tests it before saving and shows "Key replaced" on success. The account and its project channel choices stay in place.

"Postiz rejected the API key. Make a new key and paste it in Settings, Publishing."

Why: Postiz refused the saved key while sending a post: HTTP 401 (key missing or not recognized) or 403 (the key does not own that channel or post). You see this after "Post now" or "Schedule…" on a post, along with a "Publish failed" notification, and after Send now as "Send failed:" followed by this message when no post went out.

Fix: Copy the current key from Postiz under Settings > Developers > Public API. In Settings > Publishing, open the Postiz row's "..." menu under "Schedulers" and choose "Replace key". Paste the current key into "New API key". Check "Server address" too if you self-host. Click "Replace"; Threadgehog tests it before saving and shows "Key replaced" on success. The account and its project channel choices stay in place.

"Postiz rejected this key. Check it in Postiz and paste it again."

Why: The connection test ran and Postiz answered with a 401 or 403: the key was rotated or mistyped, or it does not own the channel it is being checked against. The sheet also shows channel-loading errors, and the saved account can be checked with "Test connection" in its "..." menu under "Schedulers".

Fix: Copy the current key from Postiz under Settings > Developers > Public API. If you are still on "Paste your key", correct the credentials there and wait for the automatic test, then click "Next" when it passes. For a saved account, open Settings > Publishing and open the Postiz row's "..." menu under "Schedulers" and choose "Replace key". Paste the current key into "New API key". Check "Server address" too if you self-host. Click "Replace"; Threadgehog tests it before saving and shows "Key replaced" on success. The account and its project channel choices stay in place.

"Couldn't reach Postiz. Check your connection and try again."

Why: Threadgehog's Mac could not reach Postiz during the connection test, either because the Mac was briefly offline or, on a self-hosted install, because the server address is wrong.

Fix: Check your internet connection. If you self-host, check the server address ends in /public/v1 and that the server is reachable, then click Test again.

"Postiz answered with an error: <message>"

Why: The connection test got back an error from Postiz that is not a rejected key or a network problem. After the colon, Threadgehog shows the error it got, usually "Postiz error" with the HTTP status code and Postiz's own text.

Fix: Read Postiz's message for the reason. If it does not explain itself, wait a few minutes and try again, or check your server if you self-host.

More than one Postiz entry appears under "Schedulers".

Why: The account was connected more than once. A new connection saves an account when you click "Next" after a passing key test; "Test" alone does not save one.

Fix: Open each unwanted Postiz row's "..." menu under "Schedulers", choose "Remove", and confirm. Posts already scheduled there stay scheduled. Removing an account clears project choices that used it. In Settings > Publishing, click "Choose" beside the project under "Where each project posts". In the sheet, pick the Postiz channel for each platform the project uses, then click "Done".

Send now shows "Send failed:" and a reason, such as "<project>:x: no publishing channel mapped."

Why: No post went out on that send, and Threadgehog names the first problem it hit. "no publishing channel mapped" means the project has no Postiz channel set for that network (removing a Postiz account clears choices that used it). A refused key shows the "Postiz rejected the API key" message instead. If Postiz has no X channel linked, X posts you approve, or that Auto-approve X posts queues for you, stay queued for this reason. Automatic sends skip these posts without a notice.

Fix: In Settings > Publishing, click "Choose" beside the project under "Where each project posts". In the sheet, pick the Postiz channel for each platform the project uses, then click "Done". If the channel is missing, connect it in the scheduler and click "Refresh" in the sheet. Then try "Send now" again.

A "Publish failed" notification after "Post now" or "Schedule…" with the text buffer_not_configured, invalid_provider_channel or no publishing channel mapped for project

Why: The project's channel for that network points at a channel from a different scheduler (invalid_provider_channel) or is not set at all (no publishing channel mapped for project). buffer_not_configured is Threadgehog's internal name for a target that still points at a removed account; this can only happen in a rare leftover case, since removing an account now clears the project rows that pointed at it.

Fix: In Settings > Publishing, click "Choose" beside the project under "Where each project posts". In the sheet, pick the Postiz channel for each platform the project uses, then click "Done". If the channel is missing, connect it in the scheduler and click "Refresh" in the sheet. Then try "Send now" again.

A banner: "Postiz is limiting how fast posts can be added right now. Threadgehog keeps sending on the next run."

Why: Postiz answered with HTTP 429 (too many requests). Postiz's limit is per hour on creating posts: 100 an hour on Postiz cloud, 90 by default on self-hosted installs, and 30 in Postiz's official docker-compose file.

Fix: Wait about an hour, then click Send now. Nothing in the queue is lost, and automatic sends try again on the next half-hour check. If you self-host and send often, raise API_LIMIT on your Postiz server.

A post moves back to Pending with an orange "Postiz refused this" badge and the tooltip "Postiz could not publish this post"

Why: Threadgehog checks sent posts with Postiz, and Postiz marked this one as failed, so Threadgehog moved it back to Pending and tagged it.

Fix: Check the post and its channel in Postiz and fix the problem there. Then approve the post in Threadgehog again.

A post moves back to Pending with an orange "Postiz refused this" badge whose tooltip starts "Postiz rejected this: Invalid post:"

Why: Postiz refused the post itself (HTTP 400 or 422), for example a malformed request or content Postiz would not accept. Threadgehog moves it out of the queue so it does not block the posts behind it, and the send notice reads "Sent <n> to Postiz. <n> moved back to Pending: Invalid post:" followed by the reason.

Fix: Read the reason at the end of the tooltip, edit the post, and approve it again.

An error that starts "Postiz error" followed by a status code

Why: Postiz returned an error Threadgehog has no specific message for. A 404 means Postiz could not find the channel or post, for example because the channel was removed in Postiz or a self-hosted address points to the wrong path. A 5xx code is a problem on the Postiz server.

Fix: For a 404, in Settings > Publishing, click "Choose" beside the project under "Where each project posts", then "Refresh" in the sheet. Pick the Postiz channels and click "Done". If you self-host, check that the server address ends in /public/v1; use "Replace key" in the saved account's "..." menu to correct "Server address" with the current key. For a 5xx code, wait and try again, or check your server if you self-host.

The send notice ends with "Postiz queue full for now"

Why: That channel already has the number you set ("Edit" in the account row's "..." menu under "Schedulers", default 10) scheduled in Postiz, which is as many as Threadgehog keeps there at a time.

Fix: Nothing to fix. The remaining posts stay in Threadgehog's queue and go out on later sends as Postiz publishes the scheduled ones. If a send could not hand over any post, automatic sends pause until the next 9 AM; approving a new post lifts the pause.

Questions

Where do I find my Postiz API key?

In Postiz, open Settings, then Developers, then Public API, and click the reveal icon to show the key. You can rotate it from the same page if it ever leaks.

Which Postiz plan do I need?

Any of them. Postiz's pricing page says every plan includes the API: Standard is $29 a month for 5 channels, Team $39 for 10, Pro $49 for 30 and Ultimate $99 for 100, billed monthly, and each starts with a 7-day free trial. Self-hosted installs include the API too. These are the prices listed on October 1, 2026; check postiz.com/pricing for current ones.

Where is my Postiz key stored?

In your Mac's Keychain. Threadgehog does not write it to its settings file. Publishing requests go from your Mac straight to Postiz, so the key never passes through Threadgehog's servers.

Do I need a scheduler at all?

To have posts go out automatically, yes. Threadgehog publishes by sending to Buffer, Typefully, Publer, Metricool or Postiz. Without one, choose "Export only" on setup's "How do you want to publish?" step and copy posts out yourself.

When does a queued post go out?

Each queued post gets a time Threadgehog picks from your posts a day, spread from 9 AM to 9 PM, and is scheduled in Postiz for then. Sends happen on the schedule you pick in Settings, Publishing, and only while Threadgehog is open. To skip the queue, use "Post now" or "Schedule…" from the arrow next to Approve.

Can I switch from another scheduler to Postiz?

Yes. In Settings > Publishing, click "Connect a scheduler" and finish the key and channel steps for Postiz. For each other project, click "Choose" under "Where each project posts", pick the new channels and click "Done". Existing valid channel choices stay selected until you change them. Posts already sent to the old scheduler stay scheduled there; posts still in Threadgehog's queue use each project's chosen channel on the next send. To remove the old connection, choose "Remove" from its row's "..." menu under "Schedulers" and confirm. This clears any project choices that still used that account.

What happens to my queue if Postiz is down or rate limited?

Posts stay in Threadgehog's queue. Threadgehog shows a banner that Postiz is limiting how fast posts can be added, and tries again on the next half-hour check. If the Mac is offline, automatic sends also try again on the next check. You can click Send now once Postiz is back.

Who can help if setup still fails?

Email support@threadgehog.com with the exact message Threadgehog showed, your macOS version, and whether you use Postiz cloud or a self-hosted server. Do not send your API key.

Other guides