Skip to main content

​
Overview

The Integrations API lets you register your own integrations in Opus programmatically — the provider they belong to, the integration itself with the actions it can perform, and the credential schema it authenticates with — and then connect one so a workflow can run it. Most of these endpoints author the integration catalog: the definition of an integration and the shape of its credentials, shared across your whole organization. Connect an Integration is the exception — a connection supplies the real secret values and belongs to a single workspace.

​
Base URL

All API requests should be made to the following base URL:

​
Authentication

All API endpoints require authentication with your Opus API key, sent in the x-service-key header.
Your key determines your identity and your organization. The three authoring endpoints require the Integration: Full permission at organization level — a workspace-level grant is not sufficient, because what they create belongs to the organization rather than to a workspace. Connect an Integration is the other way round: it needs Integration: Full in the workspace you are connecting into, because that is where the connection lives. A request with a missing, invalid, or expired key returns 401. Keys are rate limited — sustained bursts return 429.
Your API key is a unique, secret credential. Store it securely and never expose it in client-side code.
Your organization must be verified to author integrations. An unverified organization receives 403 from the three authoring endpoints. Contact Opus support if you need your organization verified.Connecting does not require verification — you can connect any integration you can see, including the ones Opus publishes.

​
Authoring Flow

Creating a working integration takes three calls, in order. Each returns an id the next one needs. A fourth connects it so a workflow can use it.
1

Create a Provider

A provider is the vendor or system the integration talks to — Google, Slack, your own internal service. Create one with POST /provider and keep the returned id. Reuse it for every integration from the same vendor.
2

Create the Integration

POST / registers the integration under that provider, optionally with its actions inline. Keep the returned versionId.
3

Add a Credential

POST /v/{integrationVersionId}/credential defines how the integration authenticates — which fields exist and how they render. This is the credential schema, never the secret values.
4

Connect It

POST /connect activates the integration in a workspace with the real secret values, and returns the connection a workflow refers to.
Steps 2 and 3 can be collapsed into one call: pass a credential object inside the integration body and it is created alongside it.

​
Actions and Fields

An action is one thing an integration can do. It carries an inputs and an outputs map describing its data, plus the Python code that runs when the action executes. Both maps are keyed by the field’s own variableName:
The key and the variableName inside it must match. Your code reads inputs from input_data[...] and writes outputs to result[...] using those same names. For composite types, allowedTypes[].typeDefinition describes the shape inside — for array a single-key map naming the element, for object a map of its properties. Values nest, so a list of records is array → object → properties.

​
Usage Notes

  • Authoring is org-wide, connecting is not. Providers, integrations and credentials belong to your organization and accept no workspace id. A connection belongs to the one workspace you name.
  • One credential per auth type. Adding a second credential with the same authType to the same integration returns 409.
  • A failed action does not roll back the integration. If an inline action is rejected, the integration itself may still have been created. Check before retrying, or you will end up with duplicates.
  • 400 is us, 422 is downstream. A 400 means this API rejected your body. A 422 means it passed validation here and was rejected further down — most often an email on a reserved domain.

​
Available Endpoints

Create a Provider

Register the vendor or system an integration is authored under

Create an Integration

Register a custom integration, optionally with its actions and credential

Add a Credential

Define how an integration authenticates

Connect an Integration

Activate an integration in a workspace with real credential values

Check a Connection

Read the outcome of a connection that needed authorizing