Tidenda
Start free

Guides

API overview

Authentication, scopes, rate limits, contract scope. Start here for any integration.

API overview

Tidenda exposes a small public HTTP surface for the two integration patterns most organisations need:

  • Push documents in. External feeds, importers, news agents, and scrapers post documents to POST /v1/documents.
  • Receive signed events out. Outbound webhooks fire on workflow transitions and carry signed snapshots. See Receiving webhooks.

The pages under Reference carry the per-endpoint shapes, request and response examples, and error codes. This page orients you to the authentication model and stable contract.

Stable contract

Four things are stable and the integration target:

  • POST /v1/documents — push documents in.
  • GET /v1/documents — read published documents out (query by type and updated-since; cursor-paginated).
  • GET /api/keys — fetch the trusted public-key list for verifying snapshot signatures.
  • The webhook delivery payload — described in Receiving webhooks.

The /v1/ prefix is a version marker. Breaking changes to any of these arrive under a new prefix (/v2/); the old prefix continues to serve the old shape.

That guarantee is not yet in force. The platform is pre-production, and while it is, a breaking change lands under /v1/ and is described here rather than arriving beside it under a new prefix. Read this page as the current contract rather than as a frozen one, and pin an integration to a reviewed revision of it. Parallel-versioned prefixes begin at general availability.

Anything outside the surfaces above is internal and may change without notice.

Authentication

The public surface uses per-tenant API keys. A key looks like vk_<prefix>_<secret>. The prefix is a short visible identifier that maps to a tenant; the secret is a long random suffix. The full key is shown to the operator exactly once at creation. Only the hash is stored. Lost keys must be reissued.

To use a key:

Authorization: Bearer vk_abc123_J8YOBfm5LDpFwQ...

Tenant identity is taken from the key — don't include a tenant id in the body, it would be ignored.

Scopes

Each key declares a set of scopes. The current scope set:

  • documents:create — POST /v1/documents.
  • publisher:read — GET /v1/documents, and the publisher-facing reads under /v1/publisher/* used by custom sites. Grants published content only: articles, images, audio, tags and site configuration, each at status usable. It does not reach people, private user data, workflows, or organisation settings.
  • phrases:read — GET /v1/phrases.
  • phrases:write — PUT /v1/phrases, POST /v1/phrases/import, DELETE /v1/phrases/:id.

New endpoints declare their own scopes; an existing key keeps working until you choose to grant it the new scope.

Where keys come from

An owner or admin creates a key in the Settings → API keys view. The key value is copied off the success screen at creation; the platform never stores or returns the plaintext again.

Pushing documents in

POST /v1/documents
Authorization: Bearer vk_abc123_J8YOBfm5LDpFwQ...
Content-Type: application/json

{
  "version": 1,
  "payload": {
    "type": "core/newswire",
    "title": "Cabinet reshuffle expected ahead of Thursday vote",
    "content": {
      "text": "..."
    },
    "meta": {
      "source": "your-importer"
    }
  }
}

The payload shape matches the document type's schema (see Document formats). The platform fills in id, meta.status (always draft on intake), meta.workflowId, meta.workflowVersion, and any other fields the workflow runtime owns.

The full request, response, and error reference is in API reference.

Receiving published content

Tidenda does not expose a polled fetch on the public surface. Snapshots arrive at a registered endpoint as signed webhooks when a document reaches a snapshotted status (usable or withheld). The payload includes the full snapshot JSON inline, an Ed25519 signature covering it, and an HMAC over the request body.

See Receiving webhooks for the receiver contract and Signing and signatures for the verification recipe.

Signing keys

Public, unauthenticated:

GET /api/keys

Returns the current active key id and a list of trusted public keys (active plus historical). Cache the response for around an hour; the keys change rarely. The keyId on each delivered snapshot signature picks the right key from the list.

See Signing and signatures for the full verification flow, key rotation behaviour, and sample code.

Rate limits

Two ceilings apply:

  • Per-IP volumetric ceiling — applied before key validation to shed pre-auth load.
  • Per-key budget — per-tenant ceiling on writes.

When a limit is hit the response is 429 Too Many Requests with a Retry-After header (seconds) and an envelope describing which limit was hit. The exact ceilings are operator-tunable per deployment.

Where to go next