Skip to content
Docs sections Publishing API

Publishing API

Run approved reports from your own systems

List publications, start dry or delivered runs, and poll their status from an orchestrator, scheduled job, CI workflow or authorised agent. The OpenAPI document is the contract.

This guide is for developers

You do not need the API to schedule and send reports; that is all in the app (see Publish & schedule). Share this page with whoever connects Rahoto to your other systems.

Contract and authentication

API access comes with the Pro plan and larger. Only an organisation owner or administrator can create keys: in the app, open Metrics → API access, type a New key name and press Create key, or call POST /api/v1/api-keys, which also takes an expiry of 1 to 365 days. The secret is shown once, when the key is created.

A key acts with its creator's current access: it reaches only publications whose reports that person can still read. Use a separate, expiring key for each integration, keep it in a secret manager, and never put it in report content or client-side code.

Scopes, and what you can provision today

publications:read
List publications and read one publication in your organisation.
publications:run
Start a publication run, including a dry run; select a reviewed, enabled definition.
runs:read
Read a run once its publication is verified in your organisation.

Scoped keys are not available yet

The routes enforce these scopes, but the current API-key management allowlist does not admit the three publishing scope strings, so no one can create a scoped publishing key today. An owner or administrator can create an unscoped key instead. It carries broad API access, so review that authority before you use it.

Minimal run flow

  1. List GET /publications with read access. It returns up to the first 100 non-deleted publication definitions in your organisation that the key's creator can read, including disabled definitions.
  2. Pick a reviewed, enabled publication identifier from your 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 renders the publication without delivering it. Use it while you wire up an integration, and enable delivery once the report, audience, access policy and targets have been reviewed in Rahoto.

If something goes wrong

  • 401: the key is missing, invalid, expired or revoked.
  • 403: missing scope or organisation context, or the key's creator no longer has access to the report. Do not retry unchanged.
  • 404: not available in your tenant, which is not proof the identifier never existed.
  • 409: the publication cannot run as it stands: it is disabled, its report is in the trash, or its owner has left or holds no editor seat. A person in Rahoto has to resolve it.
  • Bound retries for transient failures, and keep the returned run identifier to follow the run.

Read next

Need a workspace?

Create a publication in the editor and test it with a dry run before you enable delivery.

Start 14-day trial API reference