Operator API

An Operator API publishes a system or custom operator as a synchronous REST service. An external application submits that operator’s inputs and receives its result directly. Single-step processing such as parsing, segmentation, embedding, and information extraction fits this pattern; multi-step or long-running work is better orchestrated as a workflow.

Operator API, Model API, or workflow?

Requirement

Capability

Invoke a model directly

Genesis Model API

Invoke one published data-processing operator

Operator API

Run long or multi-step work that needs job state

A workflow and the job capability available in the deployment

Operator APIs are synchronous. The operator layer does not add a separate asynchronous job model, so callers must handle the timeout configured on the service page.

Before publishing

Confirm that:

  • the target operator version is saved and available;

  • its parameter names, types, required inputs, and defaults are correct;

  • a task compute resource is available for a non-model operator;

  • your account can manage the Catalog resource and publish the service;

  • the caller can use the configured API Key, OAuth 2.0, or public-access method.

Both system and custom operators may expose an API publishing action. Its availability depends on resource type, version state, permissions, and deployment version.

Publish and capture the contract

  1. Open Resource Center > Catalog, then open the database and operator.

  2. Select the operator version to publish and open API Service.

  3. Use the available action to publish or enable the service, then configure authentication and runtime settings.

  4. Record the service status, endpoint, request parameters, response description, and generated example.

  5. Before integrating an application, use the online test or generated example with non-sensitive test input.

The page may expose runtime settings such as timeout, maximum concurrency, and invocation frequency. The current page defines which settings are available and how they apply.

Build a request

The endpoint and JSON structure follow the operator signature. This example shows only the shape of an API Key request; it is not a fixed schema for every operator:

curl --request POST "$OPERATOR_ENDPOINT" \
  --header "Authorization: Bearer $GENESIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"input":"..."}'

The input property is a placeholder. Copy the exact field names and nesting generated for the published version. If the service uses OAuth 2.0 or public access, follow the method shown on the service page instead of sending the example API Key.

Inputs and results

  • Inputs correspond to the operator signature and the input source selected at publication time.

  • Required fields, defaults, and types belong to the published version. Versions may be incompatible.

  • The operator output determines the response structure. This page does not prescribe a universal data, result, or error object.

  • Capture the actual HTTP status, error body, and request identifier, when provided, for troubleshooting.

Manage versions safely

When changing operator logic, prefer creating and testing a new version before publishing it. After switching versions or republishing:

  1. compare the old and new parameter signatures and outputs;

  2. run a fixed set of representative inputs;

  3. review caller timeouts and retry behavior;

  4. move production traffic gradually.

Before disabling or deleting a version, check for dependent workflows, agent tools, and external applications. A successful publication message confirms the publishing operation, not the business result; verify the service with a real request.

Caller reliability

  • Set a client timeout slightly above the service timeout so connections do not wait indefinitely.

  • Retry automatically only when the operation is safe to repeat. Whether an operator has side effects depends on its implementation.

  • Apply application-side limits to large inputs, sensitive data, and concurrency.

  • Monitor HTTP failures, timeouts, and result-validation failures separately.

  • Keep credentials in a secret manager or environment variables and rotate them according to deployment policy.

Troubleshoot a call

Symptom

Check

401 or 403

Configured authentication method, credential validity, and account or application permissions

404

Full endpoint shown for the current version and whether the service is enabled

Parameter validation error

Field names, nesting, types, required inputs, and published version

Timeout or 5xx

Online test result, task compute availability, and service runtime limits

Old result after a publication

Version actually being called, republish status, and caller-side caching

For UI procedures, see Catalog management. For operator scope, see the System Operator Library. The Platform Capabilities page describes the wider API boundary.