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. These endpoints author the integration catalog: the definition of an integration and the shape of its credentials, shared across your whole organization. Connecting an integration inside a workspace — supplying the real secret values — is a separate, workspace-scoped step done in the Opus app.

​
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. Every endpoint here requires the Integration: Full permission at organization level — a workspace-level grant is not sufficient, because everything you create belongs to the organization rather than to a workspace. 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 every endpoint in this section. Contact Opus support if you need your organization verified.

​
Authoring Flow

Creating a working integration takes three calls, in order. Each returns an id the next one needs.
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.
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

  • Nothing is workspace-scoped. Providers, integrations and credentials all belong to your organization. No workspace id is accepted anywhere in this section.
  • 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