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.

Contract and authentication

An organisation owner or administrator manages keys. 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. The secret is shown once, when the key is created.

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 every non-deleted publication definition in your organisation, 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.

Safety and failure handling

  • 401: the key is missing, invalid, expired or revoked.
  • 403: missing scope or organisation context. Do not retry unchanged.
  • 404: not available in your tenant, which is not proof the identifier never existed.
  • 409: the publication is disabled. An owner has to decide.
  • 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 free API reference