Integration overview

Tidenda connects to other systems through four routes: a push API, a read API, webhooks, and a public site. This page is the map for integrators and the administrators who issue their keys.

curl -s "https://<public-api-host>/v1/documents?type=core/article&limit=10" \
  -H "Authorization: Bearer vk_a1b2c3d4_J8YOBfm5LDpFwQ..."

That one request lists the ten most recently changed published articles. Everything else on the public API follows the same pattern: a base URL, a scoped key, a JSON envelope.

Ways in and out

Route	Direction	What it does	Start here
Push API	In	POST /v1/documents creates wires, planning items and articles from your systems.	Pushing documents in
Sources	In	The platform reads RSS, Atom and JSON Feed feeds that an administrator registers, with no integration to build.	Wires: Sources
Read API	Out	GET /v1/documents lists published articles, images, audio, tags and site configuration.	API reference
Webhooks	Out	A signed request reaches your URL each time a document changes status, carrying the signed snapshot when it publishes.	Webhooks
Public site	Out	Published articles appear on a hosted site, on a preview address or your own domain.	Public site

Every pushed document enters its workflow at draft. Wires move on to usable in the same request and land in the Wires view, where editors turn them into stories; see Wires. Wires from registered sources take the same path, with the same validation, deduplication, signing and categorisation; pushing a wire works as described in Pushing documents in whether or not the organisation also has sources. meta.sourceRef names a registered source and is set by the platform only: a pushed wire that carries it has it removed. Planning items and articles stay at draft until an editor moves them on. The organisation's spelling phrases can be exported and seeded through /v1/phrases, described in the API reference.

Choose webhooks to react the moment something publishes or unpublishes, or when you need the signed copy. Choose the read API to rebuild a view on your own schedule. Many integrations use both: webhooks for change, the read API to backfill.

Base URL

Every endpoint is served from the deployment's public API host, written <public-api-host> in these docs. Document and phrase endpoints sit under /v1, as in https://<public-api-host>/v1/documents. The signing-key list sits outside it, at https://<public-api-host>/api/keys, and needs no key.

Authentication

Every /v1 request carries an API key in the Authorization header:

Authorization: Bearer vk_<prefix>_<secret>

A key belongs to one organisation, and every request made with it acts on that organisation. No request names an organisation itself.

Who creates keys. An owner or admin creates keys in Settings → API keys, names each one, and picks its scopes. The full key is shown once, on creation, and Tidenda keeps only a hash of it. A lost key cannot be shown again: revoke it and create a new one.

What a key can do. A key holds scopes, not roles. It is not a member, cannot sign in, and cannot do anything its scopes do not name.

Scope	Lets the key
documents:create	Push documents in
publisher:read	Read published content: articles, images, audio, tags, site configuration
phrases:read	Export the spelling phrases
phrases:write	Add, replace, import and delete spelling phrases

Give each integration its own key with the fewest scopes it needs. An importer needs only documents:create; a site renderer needs only publisher:read. Separate keys can be revoked separately, and each has its own rate-limit budget.

publisher:read never reaches drafts, withheld or cancelled documents, members, workflows, AI operations or organisation settings. A leaked read key exposes only what is already published.

Signed content

Published snapshots, images and approved audio quotes are signed with Ed25519. The public keys are at GET /api/keys, so a receiver can check that content is exactly what the newsroom released, even after it has passed through other systems. The read API returns current content, not signed snapshots; signed copies arrive through webhooks. See Signatures.

Stability

Tidenda is pre-production. The public docs are the contract, and the contract can still change: a breaking change is made under /v1 and documented here rather than introduced under a new prefix. Review these pages when you upgrade an integration, and keep a copy of the revision you built against.

From general availability, a breaking change will arrive under a new version prefix, such as /v2, with a migration note and a deprecation period for the old one.

Only the endpoints in the API reference and the webhook contract are supported for integrations. Any other address on a Tidenda host is internal and can change without notice.

Related pages

• API reference
• Pushing documents in
• Webhooks