Skip to content

The manual · every section kept current with each release

Vol. I · No. 130RahotoFrankfurt · EU-hosted

“The manual for the reporting runtime.”

Publishing API

Run approved reports from your own systems.

The versioned public API exposes publication definitions and runs without exposing the editor's internal runtime. Use it to connect Rahoto to an orchestrator, scheduled job, CI workflow, or authorised agent. The OpenAPI document is the machine-readable contract.

Contract and authentication

An organisation owner or administrator manages keys. Use a separate, expiring key for each integration, store it in a secret manager, and never place it in report content or client-side code. The secret is shown only when the key is created.

Publishing scopes and the current provisioning limit

publications:read
List publications and read one publication in the caller's organisation.
publications:run
Trigger a publication run, including a dry run when requested; callers must select a reviewed, enabled definition.
runs:read
Read a run after its publication is verified in the caller's organisation.

The routes enforce these scopes for a key that already carries permissions. However, the current API-key management allowlist does not admit the three publishing scope strings, so no user—including a Rahoto platform administrator—can provision a scoped publishing key through the supported key API today. Organisation owners and administrators can create only an empty-permission compatibility key for this surface; that key receives the existing broad API access and should be used only after its full authority has been reviewed. Do not present scoped publishing keys as available until the credential policy and provisioning path ship.

Minimal run flow

  1. List GET /publications with read access. The response contains every non-deleted publication definition in the caller's organisation, including disabled definitions.
  2. Select a reviewed, enabled publication identifier from the operator's own allowlist; never accept an arbitrary identifier from an untrusted prompt.
  3. Start POST /publications/{id}/runs. Send {"dryRun":true} to render without delivery.
  4. Poll GET /runs/{id} with bounded retries and backoff.
curl --fail-with-body \
  --header "X-API-Key: $RAHOTO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"dryRun":true}' \
  https://api.rahoto.com/api/v1/public/publications/PUBLICATION_ID/runs

A dry run prevents delivery but still exercises the publication runtime. Use it while wiring an integration, then enable delivery only after the report, audience, access policy, and targets have been reviewed in Rahoto.

Safety and failure handling

  • Treat 401 as a missing, invalid, expired, or revoked key.
  • Treat 403 as missing scope or organisation context; do not retry unchanged.
  • Treat 404 as unavailable in the caller's tenant, not proof that an identifier never existed.
  • Respect 409 for a disabled publication and require an owner decision.
  • Bound retries for transient failures and preserve the returned run identifier for observation.

See Agent operation for tool-design and approval boundaries.

Need a workspace?

Start free, create a publication in the editor, and use a dry run before enabling delivery.