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
}
Integrations
Create an Integration
Register a custom integration, optionally with its actions and credential
POST
/
api
/
v1
/
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
Body Parameters
The integration is nested under anintegration key.
Integration icon as a base64-encoded SVG (or PNG) — a plain string, with no
data: prefix. Maximum 65535 characters.Integration categories. Between 1 and 5 entries, for example
machine_learning_and_ai_services or collaboration_tools.The provider this integration is authored under, from Create a Provider.
Minimum plan an organization needs to connect this integration —
core, pro or scale.Show the “beta” badge on the integration tile. Accepted on create but not currently echoed back in the response.
Actions to create alongside the integration. Maximum 50. See Action 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
The external endpoint this action talks to. Metadata only —
code is what actually executes. Maximum 2048 characters.The action’s input schema, keyed by each field’s
variableName. See Field object.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 insideinputs and outputs. The map key must equal the field’s variableName.
Programmatic key. Referenced from
code as input_data[<variableName>] for inputs, or result[<variableName>] for outputs.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.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
The integration version id. Use it as
{integrationVersionId} in Add a Credential.The credential created inline, as
{ credentialId, credentialVersionId, name }. null when none was supplied.Errors
Invalid body — a missing required field, a value over its limit, more than 5 categories, or more than 50 actions.
Your organization is not verified to author integrations, or the key owner lacks the Integration: Full permission in the organization.
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
}
Was this page helpful?