Create an Integration

curl --request POST \
  --url https://operator.opus.com/api/v1/integration \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: {YOUR_SERVICE_KEY}' \
  --data '{
    "integration": {
      "name": "Acme Search",
      "description": "Search the web using the Acme API",
      "icon": "{BASE64_ICON}",
      "category": ["machine_learning_and_ai_services"],
      "providerId": "{PROVIDER_ID}",
      "actions": [
        {
          "name": "Search",
          "description": "Run a search query",
          "endpoint": "https://api.acme.com/v1/search",
          "code": "result[\"items\"] = search(input_data[\"query\"], credential_value)",
          "inputs": {
            "query": {
              "id": "1",
              "variableName": "query",
              "displayName": "Query",
              "allowedTypes": [{ "type": "str" }]
            }
          },
          "outputs": {
            "items": {
              "id": "1",
              "variableName": "items",
              "displayName": "Items",
              "allowedTypes": [{ "type": "array" }]
            }
          }
        }
      ]
    }
  }'

import requests

url = "https://operator.opus.com/api/v1/integration"
headers = {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
    "integration": {
        "name": "Acme Search",
        "description": "Search the web using the Acme API",
        "icon": "{BASE64_ICON}",
        "category": ["machine_learning_and_ai_services"],
        "providerId": "{PROVIDER_ID}",
        "actions": [
            {
                "name": "Search",
                "endpoint": "https://api.acme.com/v1/search",
                "code": 'result["items"] = search(input_data["query"], credential_value)',
                "inputs": {
                    "query": {
                        "id": "1",
                        "variableName": "query",
                        "displayName": "Query",
                        "allowedTypes": [{"type": "str"}],
                    }
                },
                "outputs": {
                    "items": {
                        "id": "1",
                        "variableName": "items",
                        "displayName": "Items",
                        "allowedTypes": [{"type": "array"}],
                    }
                },
            }
        ],
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const response = await fetch("https://operator.opus.com/api/v1/integration", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}",
  },
  body: JSON.stringify({
    integration: {
      name: "Acme Search",
      description: "Search the web using the Acme API",
      icon: "{BASE64_ICON}",
      category: ["machine_learning_and_ai_services"],
      providerId: "{PROVIDER_ID}",
      actions: [
        {
          name: "Search",
          endpoint: "https://api.acme.com/v1/search",
          code: 'result["items"] = search(input_data["query"], credential_value)',
          inputs: {
            query: {
              id: "1",
              variableName: "query",
              displayName: "Query",
              allowedTypes: [{ type: "str" }],
            },
          },
          outputs: {
            items: {
              id: "1",
              variableName: "items",
              displayName: "Items",
              allowedTypes: [{ type: "array" }],
            },
          },
        },
      ],
    },
  }),
});

const data = await response.json();
console.log(data);

{
  "id": "{INTEGRATION_ID}",
  "name": "Acme Search",
  "description": "Search the web using the Acme API",
  "icon": "{BASE64_ICON}",
  "category": ["machine_learning_and_ai_services"],
  "requiredPlan": "core",
  "status": "active",
  "providerId": "{PROVIDER_ID}",
  "isNew": true,
  "isPopular": false,
  "versionId": "{INTEGRATION_VERSION_ID}",
  "createdActions": [
    {
      "actionId": "{ACTION_ID}",
      "actionVersionId": "{ACTION_VERSION_ID}",
      "name": "Search"
    }
  ],
  "createdCredential": null
}

POST

api

integration

curl --request POST \
  --url https://operator.opus.com/api/v1/integration \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: {YOUR_SERVICE_KEY}' \
  --data '{
    "integration": {
      "name": "Acme Search",
      "description": "Search the web using the Acme API",
      "icon": "{BASE64_ICON}",
      "category": ["machine_learning_and_ai_services"],
      "providerId": "{PROVIDER_ID}",
      "actions": [
        {
          "name": "Search",
          "description": "Run a search query",
          "endpoint": "https://api.acme.com/v1/search",
          "code": "result[\"items\"] = search(input_data[\"query\"], credential_value)",
          "inputs": {
            "query": {
              "id": "1",
              "variableName": "query",
              "displayName": "Query",
              "allowedTypes": [{ "type": "str" }]
            }
          },
          "outputs": {
            "items": {
              "id": "1",
              "variableName": "items",
              "displayName": "Items",
              "allowedTypes": [{ "type": "array" }]
            }
          }
        }
      ]
    }
  }'

import requests

url = "https://operator.opus.com/api/v1/integration"
headers = {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
    "integration": {
        "name": "Acme Search",
        "description": "Search the web using the Acme API",
        "icon": "{BASE64_ICON}",
        "category": ["machine_learning_and_ai_services"],
        "providerId": "{PROVIDER_ID}",
        "actions": [
            {
                "name": "Search",
                "endpoint": "https://api.acme.com/v1/search",
                "code": 'result["items"] = search(input_data["query"], credential_value)',
                "inputs": {
                    "query": {
                        "id": "1",
                        "variableName": "query",
                        "displayName": "Query",
                        "allowedTypes": [{"type": "str"}],
                    }
                },
                "outputs": {
                    "items": {
                        "id": "1",
                        "variableName": "items",
                        "displayName": "Items",
                        "allowedTypes": [{"type": "array"}],
                    }
                },
            }
        ],
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const response = await fetch("https://operator.opus.com/api/v1/integration", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}",
  },
  body: JSON.stringify({
    integration: {
      name: "Acme Search",
      description: "Search the web using the Acme API",
      icon: "{BASE64_ICON}",
      category: ["machine_learning_and_ai_services"],
      providerId: "{PROVIDER_ID}",
      actions: [
        {
          name: "Search",
          endpoint: "https://api.acme.com/v1/search",
          code: 'result["items"] = search(input_data["query"], credential_value)',
          inputs: {
            query: {
              id: "1",
              variableName: "query",
              displayName: "Query",
              allowedTypes: [{ type: "str" }],
            },
          },
          outputs: {
            items: {
              id: "1",
              variableName: "items",
              displayName: "Items",
              allowedTypes: [{ type: "array" }],
            },
          },
        },
      ],
    },
  }),
});

const data = await response.json();
console.log(data);

{
  "id": "{INTEGRATION_ID}",
  "name": "Acme Search",
  "description": "Search the web using the Acme API",
  "icon": "{BASE64_ICON}",
  "category": ["machine_learning_and_ai_services"],
  "requiredPlan": "core",
  "status": "active",
  "providerId": "{PROVIDER_ID}",
  "isNew": true,
  "isPopular": false,
  "versionId": "{INTEGRATION_VERSION_ID}",
  "createdActions": [
    {
      "actionId": "{ACTION_ID}",
      "actionVersionId": "{ACTION_VERSION_ID}",
      "name": "Search"
    }
  ],
  "createdCredential": null
}

Register a custom integration under your organization. Optionally supply actions[] and a single credential inline, so an integration can be authored in one call. Returns versionId, which you pass to Add a Credential. Requires the Integration: Full permission at organization level.

integration.providerId must belong to your organization. Create a provider first if you do not have one.

Headers

string

required

Your API authentication key

Body Parameters

The integration is nested under an integration key.

object

required

The integration to create. Fields below.

string

required

Integration name. Maximum 255 characters.

string

required

Integration icon as a base64-encoded SVG (or PNG) — a plain string, with no data: prefix. Maximum 65535 characters.

string[]

required

Integration categories. Between 1 and 5 entries, for example machine_learning_and_ai_services or collaboration_tools.

string

required

The provider this integration is authored under, from Create a Provider.

string

Integration description. Maximum 2048 characters.

string

default:"core"

Minimum plan an organization needs to connect this integration — core, pro or scale.

string

Integration status — active, inactive, soon or deprecated.

boolean

Show the “new” badge on the integration tile.

boolean

Show the “popular” badge on the integration tile.

boolean

Show the “beta” badge on the integration tile. Accepted on create but not currently echoed back in the response.

object[]

Actions to create alongside the integration. Maximum 50. See Action object.

object

A credential to create alongside the integration. Same shape as the body of Add a Credential.

Your organization is always taken from the API key — it cannot be set in the body. Nothing here is workspace-scoped.

Action object

string

required

Action name. Maximum 255 characters.

string

required

The external endpoint this action talks to. Metadata only — code is what actually executes. Maximum 2048 characters.

object

required

The action’s input schema, keyed by each field’s variableName. See Field object.

object

required

The action’s output schema, keyed by each field’s variableName.

string

Action description. Maximum 2048 characters.

string

Python source that runs when the action executes. Evaluated in the global scope, not wrapped in a function: read caller values from input_data[...] and the connected secret from credential_value, then assign to result[...]. Maximum 65535 characters.

Field object

Each value inside inputs and outputs. The map key must equal the field’s variableName.

string

required

Positional identifier, 1-indexed as a string — "1", "2", and so on.

string

required

Programmatic key. Referenced from code as input_data[<variableName>] for inputs, or result[<variableName>] for outputs.

string

required

Human-readable label rendered in the workflow builder.

object[]

required

Value types this field accepts. Between 1 and 11 entries. Each has a type — one of int, float, bool, str, object, file, array, date, binary, json_string, node — plus optional typeDefinition and typeDefinitionEnforced.

string

Description shown next to the field in the builder. Maximum 2048 characters.

any

Pre-filled default value. Its type must match one of allowedTypes.

boolean

default:"false"

When true, the workflow may omit this field at execute time.

string[]

Free-form tags the builder uses for grouping and filtering. Maximum 20.

object[]

Enum-style choice list. When non-empty the builder renders a dropdown. Maximum 20.

string[]

Top-level field names the builder locks. Maximum 20.

boolean

default:"true"

When false, the builder hides the “remove field” affordance.

For composite types, typeDefinition describes the shape inside: for array, a single-key map naming the element; for object, a map of its properties. Each value is itself a field definition and may nest further, so a list of records is array → object → properties. Maximum 50 entries per map.

Response

string

required

The integration id.

string

required

The integration version id. Use it as {integrationVersionId} in Add a Credential.

string

required

Integration name.

string

required

Integration description.

string

required

Integration icon.

string[]

required

Integration categories.

string

required

Minimum plan needed to connect it.

string

required

Integration status.

string

required

The provider the integration was authored under.

boolean

required

Whether the “new” badge is shown.

boolean

required

Whether the “popular” badge is shown.

object[]

Actions created inline, each { actionId, actionVersionId, name }.

object

The credential created inline, as { credentialId, credentialVersionId, name }. null when none was supplied.

Errors

Bad Request

Invalid body — a missing required field, a value over its limit, more than 5 categories, or more than 50 actions.

Unauthorized

Missing, invalid, or expired API key.

Forbidden

Your organization is not verified to author integrations, or the key owner lacks the Integration: Full permission in the organization.

Unprocessable Entity

Rejected downstream after passing validation here.

An inline action that fails does not roll back the integration — the integration row may already exist. Check before retrying, or you will create duplicates.

curl --request POST \
  --url https://operator.opus.com/api/v1/integration \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: {YOUR_SERVICE_KEY}' \
  --data '{
    "integration": {
      "name": "Acme Search",
      "description": "Search the web using the Acme API",
      "icon": "{BASE64_ICON}",
      "category": ["machine_learning_and_ai_services"],
      "providerId": "{PROVIDER_ID}",
      "actions": [
        {
          "name": "Search",
          "description": "Run a search query",
          "endpoint": "https://api.acme.com/v1/search",
          "code": "result[\"items\"] = search(input_data[\"query\"], credential_value)",
          "inputs": {
            "query": {
              "id": "1",
              "variableName": "query",
              "displayName": "Query",
              "allowedTypes": [{ "type": "str" }]
            }
          },
          "outputs": {
            "items": {
              "id": "1",
              "variableName": "items",
              "displayName": "Items",
              "allowedTypes": [{ "type": "array" }]
            }
          }
        }
      ]
    }
  }'

import requests

url = "https://operator.opus.com/api/v1/integration"
headers = {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
    "integration": {
        "name": "Acme Search",
        "description": "Search the web using the Acme API",
        "icon": "{BASE64_ICON}",
        "category": ["machine_learning_and_ai_services"],
        "providerId": "{PROVIDER_ID}",
        "actions": [
            {
                "name": "Search",
                "endpoint": "https://api.acme.com/v1/search",
                "code": 'result["items"] = search(input_data["query"], credential_value)',
                "inputs": {
                    "query": {
                        "id": "1",
                        "variableName": "query",
                        "displayName": "Query",
                        "allowedTypes": [{"type": "str"}],
                    }
                },
                "outputs": {
                    "items": {
                        "id": "1",
                        "variableName": "items",
                        "displayName": "Items",
                        "allowedTypes": [{"type": "array"}],
                    }
                },
            }
        ],
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const response = await fetch("https://operator.opus.com/api/v1/integration", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}",
  },
  body: JSON.stringify({
    integration: {
      name: "Acme Search",
      description: "Search the web using the Acme API",
      icon: "{BASE64_ICON}",
      category: ["machine_learning_and_ai_services"],
      providerId: "{PROVIDER_ID}",
      actions: [
        {
          name: "Search",
          endpoint: "https://api.acme.com/v1/search",
          code: 'result["items"] = search(input_data["query"], credential_value)',
          inputs: {
            query: {
              id: "1",
              variableName: "query",
              displayName: "Query",
              allowedTypes: [{ type: "str" }],
            },
          },
          outputs: {
            items: {
              id: "1",
              variableName: "items",
              displayName: "Items",
              allowedTypes: [{ type: "array" }],
            },
          },
        },
      ],
    },
  }),
});

const data = await response.json();
console.log(data);

{
  "id": "{INTEGRATION_ID}",
  "name": "Acme Search",
  "description": "Search the web using the Acme API",
  "icon": "{BASE64_ICON}",
  "category": ["machine_learning_and_ai_services"],
  "requiredPlan": "core",
  "status": "active",
  "providerId": "{PROVIDER_ID}",
  "isNew": true,
  "isPopular": false,
  "versionId": "{INTEGRATION_VERSION_ID}",
  "createdActions": [
    {
      "actionId": "{ACTION_ID}",
      "actionVersionId": "{ACTION_VERSION_ID}",
      "name": "Search"
    }
  ],
  "createdCredential": null
}

Get Started

Workflows

Cases

Files

Business Process Discovery

Integrations

Deprecated

Create an Integration

Headers

Body Parameters

Action object

Field object

Response

Errors

​Headers

​Body Parameters

​Action object

​Field object

​Response

​Errors

Headers

Body Parameters

Action object

Field object

Response

Errors