The automation API#

Reportworq exposes a small HTTP API that lets an external process trigger and monitor job execution without using the web UI or the built-in scheduler. It is the only supported way to drive a job from outside Reportworq, and it is the substrate under the pre-built Turbo Integrator, Workato, and Task Scheduler integrations.

This page is written for administrators who enable the API and mint tokens, and for integration users who build the automated caller. It explains the two delivery models and their key models. To make actual calls, see Run a job by API.

When to use it. Reach for the API when automation cannot be expressed as a preset schedule, or must be triggered by another system's event, for example regenerating a reporting pack the moment a nightly data load finishes. For time-based runs, prefer the native scheduler. The API is positioned as a complement to the scheduler, not a replacement for it.

Two ways to reach the same commands#

The same command set is delivered two ways from the same server.

Both are versioned under /api/v1/. Which one you choose depends on where the caller lives: on the same network as the server (Local), or out on the internet (Cloud).

The two key models are opposite (the common bug)#

This is the fact to internalize before wiring anything, because mixing the two mental models is the most common integration mistake.

• Local API: a separate key per workspace. There is no workspace parameter. The access token you present is the workspace selector, Reportworq matches it against each workspace and resolves scope from the match. A token minted in the wrong workspace silently targets that workspace's jobs.
• Cloud API: one global key plus ?workspace=. A single Cloud Connector token covers the server, and you name the workspace with a ?workspace={name} querystring, matched by name, case-insensitively.

The ?workspace= querystring is required once more than one workspace exists, and a single-workspace instance may omit it (the relay defaults to the sole workspace). On a multi-workspace instance, omitting it does not default, the call is rejected with a "missing or unknown workspace" message.

Cloud needs only outbound 443#

The Cloud API opens no inbound port. The server dials out to CloudHub over 443 and CloudHub forwards requests down that connection, so the Reportworq server itself never needs to be reachable from the internet. This is what makes the Cloud API attractive to security teams: automation from a SaaS caller without opening the firewall. Cloud calls are subject to short Azure maintenance windows, so a robust caller retries on a transient outage.

Enabling and gating#

• The API is a licensed capability. The API entitlement on your license must be present, or an API command is refused with HTTP 400 and the message "REST API not available for this license". This is a hard block, distinct from both "The Reportworq API is disabled" (the per-workspace toggle) and "Invalid Access Token". The version and license endpoints, output downloads, the contribution upload preview, the MCP server, and CloudHub setup are deliberately not gated by it. See Licensing and entitlements.
• The Local API is enabled per workspace. Even with a valid token, if that workspace's API is disabled the call is refused with "The Reportworq API is disabled." That message is distinct from "Invalid Access Token", so if a correct token fails, check the enable toggle before assuming a bad key. Enable and regenerate the token in the admin API settings; see Server configuration.
• The Cloud Connector must be enabled for the Cloud API. Changing the Cloud token breaks existing automations built on the old one, so rotate deliberately.

Tokens should be shared only with the developers who build the callers.

What the commands cover#

The API is a small, five-command surface, and two older commands are retired:

• ping, a liveness probe.
• list, the jobs available to run.
• run, execute a job, with optional parameter and distribution overrides, returning a job id immediately.
• status, the current state of a running job.
• cancel, terminate a running job.
• info and history are deprecated and return 404, not 405. They are deliberate deprecation stubs, so a client that treats 404 as "wrong URL" will misdiagnose them. Do not build against them.

The detail of each command, and how to filter a single run to a specific output type and destination, is in Run a job by API.

Going deeper. To run and monitor a job, and to send one job's output as a PDF by email while another caller gets the same job as a PowerPoint by Slack, see Run a job by API. To launch jobs from a planning system, an iPaaS, or the OS scheduler, see Turbo Integrator, Workato, and Task Scheduler.