Omniscope APIs : data querying, automation, custom experiences

Apart from being a complete BI data analytics tool, Omniscope is also an integration and extensible platform. 

A family of REST and JavaScript APIs lets you:

• Trigger and parameterise workflows

• Schedule and orchestrate complex tasks

• Create projects programmatically from templates with parameters

• Query and transform report data as JSON 

• Build your own custom data routine or visual components and mini-apps inside Omniscope

This article gives a practical overview of all the main APIs available in Omniscope today, how they fit together, and where to find the detailed Swagger / code-level docs.

We’ll cover:

1. Automation API family

   • Workflow REST API

   • Project REST API

   • Scheduler REST API

2. Custom View JavaScript API

3. Query API (JS + REST)

4. Custom blocks & “bring your own API” patterns

5. How to choose the right API for your use case

1. Automation API family (Scheduler, Workflow, Project)

Omniscope groups several REST endpoints under what we often call the Automation API: Scheduler API, Workflow API and Project API. These let you integrate Omniscope into other tools and scripts to execute workflows, call scheduler tasks and create projects from templates.

At a high level:

• Workflow REST API : trigger workflow execution and manage project parameters on a specific .iox project. 

• Project REST API : create new Omniscope projects from templates, with parameters, via REST.

• Scheduler REST API – execute existing scheduler tasks or submit new tasks/actions, and monitor or cancel jobs.

All three share common ideas:

• They’re HTTP-based (mostly JSON, Scheduler optionally uses XML payload for task definitions).

• They rely on Omniscope permissions (specific API-related permissions must be granted) and your server’s authentication (OpenID, “List of users” + basic auth).

• Each has its own Swagger endpoint so you can explore and test calls directly from your Omniscope server.

Let’s look at each.

1.1 Workflow REST API

The Workflow REST API lets you programmatically start and monitor workflow runs on a single project, and get or update project parameters. Read more.

Key capabilities:

1. Execute a workflow

2. Lambda workflow execution,  for parametrised, per-request workflows, you can use a “lambda execution”: Omniscope clones the project, sets project parameters, runs it, and (optionally) cleans up after completion.

3. Trigger workflow via file upload (from a Report) . Used typically in combination with a Custom View in a Report UI to upload a file and immediately trigger a workflow execution using that file.

4. Monitor workflow state

5. Project Parameters API 

   • List all parameters

   • Get a single parameter:

   • Update parameters:

6. Workflow Swagger docs

   • You can test and inspect the full Workflow API from Swagger at:
     http[s]://<hostname>[:port]/<path-to-file>/w/meta 

Typical uses:

• “Refresh this project’s data and rebuild outputs” from an external system

• “Run this specific subset of blocks” (e.g. an export chain)

• “Set parameters and immediately execute” – either as lambda or in-place

1.2 Project REST API

The Project REST API is focused on creating new Omniscope projects from templates and setting their parameters on creation. Read more

It lives under the folder where projects are stored.

Key endpoints:

1. Swagger docs for a particular folder:
   http[s]://<hostname>[:port]/<path-to-folder>/_api_/v1/meta Omniscope Help Center

2. Create a project, optionally from a template , with parameters

3. List available project templates

Typical uses:

• Spin up “per-client” or “per-report” projects from a master template

• CI/CD-like deployments where a script creates or refreshes projects from a catalogue

• Combining with Workflow API to “create project → set parameters → run workflow →  deploy a report" for custom built data apps.

1.3 Scheduler REST API

The Scheduler REST API is your integration point with the central Omniscope Scheduler: executing existing tasks, submitting new ad-hoc tasks/actions, and querying or canceling jobs. Read more.

You’ll usually use this when you want Omniscope to act as an orchestrator or be orchestrated by another tool.

Key endpoints

• Swagger docs:
  http[s]://<hostname>[:port]/_admin_/scheduler/api/v1/meta 

• Execute an existing Scheduler task:

• Execute a new task/action defined in the payload

• Get job status

• List all jobs

• Cancel / delete a job

You also get a Scheduler Jobs page in the Admin app where API-submitted jobs can be inspected, and results are logged in Scheduler log files.

Typical uses:

• External platforms triggering tasks via Scheduler

• DevOps tools kicking off end-to-end data pipelines, then polling job status

• Integrations where you want Omniscope to be a task executor for custom-defined chains

2. Custom View JavaScript API

The Custom View API lets you build your own visual components and mini-apps inside Omniscope using HTML, CSS and JavaScript. Read more

You include the omniscope.js library in your custom view’s index.html:

<script src="/_global_/customview/v1/omniscope.js"></script>

Once loaded, you get access to the omniscope.view API, which is the main bridge between your custom view and Omniscope.

Key concepts

• Context – a JSON object describing the view configuration and state (current filters, selections, options, etc.). Accessible via omniscope.view.context().

• Methods – helpers like:

  • endpoint() – returns the endpoint for executing Query API calls for this view.

  • busy(boolean) – tell Omniscope when the view is loading / rendering.

  • updated() – notify Omniscope that you changed the context.

  • on, once, off – attach/detach event listeners.

• Events – e.g.:

  • load – fired when the view is loaded; event.data is the initial context.

  • resize – when the view or browser resizes.

  • update – when context changes.

  • action – for user-triggered actions defined in the view’s manifest.

Typical uses:

• Custom charts (e.g. D3, Highcharts, your own visual components) that stay wired into Omniscope’s filters and selections. Read more

• Control panels / parameter editors built directly in the report UI (e.g. switch project parameters, toggle workflows via Workflow API). 

• Custom forms that upload files and call Workflow or Scheduler APIs behind the scenes.

Critically, omniscope.view.endpoint() is the key piece that ties the Custom View API to the Query API.

3. Query API (JS helper + REST)

The Query API is the data access layer underneath Omniscope reports. It exposes the data backing a report or a block as queryable endpoints, where queries and results are JSON objects. It can be used:

• Inside Omniscope, from a Custom View via omniscope.query.builder(endpoint)

• Externally, via REST endpoints documented in the Query API Swagger UI (e.g. in the public sandbox at https://omniscope.me/_global_/query/sample/v1/meta/). More docs here

This is usually what you want when someone says:

“Instead of exporting CSVs, can Omniscope expose this dataset so we can query it over an API and receive JSON?”

3.1 Query API in your custom view (JavaScript)

The JS helper lets you build and execute queries declaratively. A typical pattern looks like this: (Tutorial here)

omniscope.query  .builder(omniscope.view.endpoint())  .table({    groupings: [],    measures: [{ function: "RECORD_COUNT" }]  })  .on("error", function (event) {    if (event.data.error) console.log(event.data.error);    omniscope.view.error(event.data.message, event.data.internal);  })  .on("load", function (event) {    console.log(event.data.records[0][0]); // record count  })  .execute();

Breaking that down:

1. Create a builder
   omniscope.query.builder(endpoint) – endpoint is typically omniscope.view.endpoint().

2. Choose a query method (Read more)

   • table(query) – tabular data, similar to SELECT ... GROUP BY in SQL.

   • formula(query) – evaluate a formula and return a scalar or small result.

   • batch(query) – run multiple queries in one call.

   • schema() / schema(query) – fetch schema information (fields, types), optionally filtered by a query.

3. Supply a query object
   For a basic aggregated table, you can pass a SimpleQuery like: 

{  "groupings": [    {      "inputField": "Country",      "type": "UNIQUE_VALUES",      "name": "Country"    }  ],  "measures": [    {      "name": "Record count",      "inputField": "Country",      "function": "RECORD_COUNT"    }  ],  "filter": {    "type": "AND",    "filters": [      {        "type": "FIELD_VALUE",        "inputField": "Year",        "operator": ">=",        "value": 2020      }    ]  },  "sorts": [    {      "inputField": "Record count",      "direction": "DESCENDING"    }  ],  "range": {    "start": 0,    "length": 100  }
}

Fields like groupings, measures, filter, sorts, range are all described in the Query API JSON schema and tutorials.

4. Attach callbacks and execute

   • .on("load", handler) – handle successful responses; result objects include a schema and records array.

   • .on("error", handler) – handle network / HTTP / JSON errors.

   • .execute() – actually perform the HTTP request. 

3.2 Query API as a REST endpoint

The same query model used by the JS helper is exposed as plain REST endpoints with Swagger documentation.

From the docs:

• The Query API reference lists methods like table(query), formula(query), batch(query), schema() and schema(query) and notes that you can explore and test them via Swagger from a per-file Query API docs link. 

• The Query API tutorials explicitly mention “REST API Swagger docs including a facility to try out queries in the browser”. 

In practice:

• Each data source / block in a Report (or a Report itself) has a corresponding Query endpoint, which you can see in the Query API Swagger UI for that file.

• External systems can:

  • Send a POST with a JSON query object (matching the schema above), and

  • Receive a JSON response with schema + records (or another output type depending on the endpoint).

For example, in our public sandbox, you can open:

• https://omniscope.me/_global_/query/sample/v1/meta/ – Query API Swagger index showing available endpoints for a sample project.

From there you can discover the exact REST paths your application should call (e.g. table-style query, formula endpoint, etc.).

3.3 Typical Query API use cases

• Replacing CSV exports: expose the same data as a Query API endpoint that returns JSON, optionally matching a specific schema using a custom layer.

• Client-side applications: front-end apps built in React / Vue / Angular / etc. can call the Query API directly, benefiting from Omniscope’s filtering, aggregation and security.

• Custom views as “API wrappers”: build a Custom View that calls the Query API and then transforms / re-exposes data in a specific structure your client expects.

4. Custom blocks

Omniscope supports custom blocks in the workflow, so you can extend the core blocks with your custom ones, say to add yet another data connectors, analytics algo, connect to external systems , AI models, and whatnot, by wrapping your own Python or R logic in a new custom block. Here the typical use cases are basically up to your imagination. Some examples in the GitHub repo here

Combined with the Automation APIs that means extending and defining custom data transformations / data pipelines and automating it all.

5. Choosing the right API

Here’s a quick decision guide: