A publish call does more than forward your text to four APIs. Knowing what happens in between
explains most of the behaviour you will build against.
One post, many targets
A publish call creates one post with one target per account. Targets are attempted
concurrently and settle independently, which is why a response can report Instagram published,
LinkedIn failed, and Threads published-with-a-failed-comment all at once.Everything Chirio returns is organised that way: post carries what you sent, post.targets
carries what each network did with it.
What happens on a publish
Your key is resolved to a project. Everything the request can see — accounts, posts,
usage — is scoped to it.
The body is validated, then your accounts are checked: they must exist, belong to your
project, and match the platform you named.
Each network's own rules are applied — caption length, media counts, whether video and
images can be mixed. A violation on any target rejects the whole request before anything
publishes.
Your quota is checked, still before any network call.
The post is recorded, with its idempotency key, so a retry can never publish twice.
Targets fan out concurrently. Each one refreshes its token if needed, uploads media,
waits for the network to finish processing, publishes, posts the first comment, and records
the outcome.
Every outcome comes back to you.
Everything you can fix is checked first
Steps 2 to 4 are ordered so that a request you got wrong is refused before a single byte reaches a network. That is why a 400 never leaves a half-published post behind.
Per-network adapters
Each network is handled by its own adapter, which owns that platform's OAuth, media handling,
publishing, comment support and token refresh. Everything above them — authentication, quota,
fan-out, retries, history — is shared.The practical consequence is that the differences you have to care about are exactly the ones
documented on the platform pages: limits, media rules, whether comments
work. Everything else behaves identically whichever network you target.
Tenancy
Your project is the boundary. It owns your API keys, your connected accounts and your post
history, and no request can read across it. If you are building a product that publishes for
your own users, one project per customer keeps their accounts and history separate.
How your data is held
Platform tokens are encrypted at rest with AES-256-GCM and are never returned by any
endpoint, including to you.
API keys are stored as SHA-256 hashes. The raw key exists only in the response that
created it — nobody, including Chirio, can recover it afterwards.
Media is never stored. You pass public URLs; the networks fetch from them at publish
time.
When a user revokes access at the network, the tokens are deleted without anyone having
to act. See Revocation and deletion.
What Chirio deliberately does not do
Why
**Host media**
Storage, CDN, scanning and retention are their own product
**Schedule posts**
You own the clock; Chirio publishes when you call it
**Send webhooks**
Poll `GET /api/v1/posts/:id` for targets still settling
