curl --request POST \
--url https://operator.opus.com/api/v1/integration/v/{INTEGRATION_VERSION_ID}/action \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"action": {
"name": "Search Documents",
"description": "Search the Acme document index",
"endpoint": "https://api.acme.com/v1/search",
"inputs": {
"query": {
"id": "1",
"variableName": "query",
"displayName": "Query",
"description": "What to search for",
"isNullable": false,
"allowedTypes": [{ "type": "str" }]
}
},
"outputs": {
"results": {
"id": "1",
"variableName": "results",
"displayName": "Results",
"allowedTypes": [{ "type": "array" }]
}
},
"code": "import requests\nresponse = requests.get(\n \"https://api.acme.com/v1/search\",\n params={\"q\": input_data[\"query\"]},\n headers={\"Authorization\": f\"Bearer {credential_value}\"},\n)\nresult[\"results\"] = response.json()[\"items\"]\n"
}
}'
import requests
version_id = "{INTEGRATION_VERSION_ID}"
url = f"https://operator.opus.com/api/v1/integration/v/{version_id}/action"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"action": {
"name": "Search Documents",
"description": "Search the Acme document index",
"endpoint": "https://api.acme.com/v1/search",
"inputs": {
"query": {
"id": "1",
"variableName": "query",
"displayName": "Query",
"description": "What to search for",
"isNullable": False,
"allowedTypes": [{"type": "str"}],
}
},
"outputs": {
"results": {
"id": "1",
"variableName": "results",
"displayName": "Results",
"allowedTypes": [{"type": "array"}],
}
},
"code": (
"import requests\n"
"response = requests.get(\n"
' "https://api.acme.com/v1/search",\n'
' params={"q": input_data["query"]},\n'
' headers={"Authorization": f"Bearer {credential_value}"},\n'
")\n"
'result["results"] = response.json()["items"]\n'
),
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const versionId = "{INTEGRATION_VERSION_ID}";
const response = await fetch(
`https://operator.opus.com/api/v1/integration/v/${versionId}/action`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
action: {
name: "Search Documents",
description: "Search the Acme document index",
endpoint: "https://api.acme.com/v1/search",
inputs: {
query: {
id: "1",
variableName: "query",
displayName: "Query",
description: "What to search for",
isNullable: false,
allowedTypes: [{ type: "str" }],
},
},
outputs: {
results: {
id: "1",
variableName: "results",
displayName: "Results",
allowedTypes: [{ type: "array" }],
},
},
code: [
"import requests",
"response = requests.get(",
' "https://api.acme.com/v1/search",',
' params={"q": input_data["query"]},',
' headers={"Authorization": f"Bearer {credential_value}"},',
")",
'result["results"] = response.json()["items"]',
].join("\n"),
},
}),
}
);
const data = await response.json();
console.log(data);
{
"actionId": "{ACTION_ID}",
"actionVersionId": "{ACTION_VERSION_ID}"
}
Integrations
Add an Action
Add an action to an integration that already exists
POST
/
api
/
v1
/
integration
/
v
/
{integrationVersionId}
/
action
curl --request POST \
--url https://operator.opus.com/api/v1/integration/v/{INTEGRATION_VERSION_ID}/action \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"action": {
"name": "Search Documents",
"description": "Search the Acme document index",
"endpoint": "https://api.acme.com/v1/search",
"inputs": {
"query": {
"id": "1",
"variableName": "query",
"displayName": "Query",
"description": "What to search for",
"isNullable": false,
"allowedTypes": [{ "type": "str" }]
}
},
"outputs": {
"results": {
"id": "1",
"variableName": "results",
"displayName": "Results",
"allowedTypes": [{ "type": "array" }]
}
},
"code": "import requests\nresponse = requests.get(\n \"https://api.acme.com/v1/search\",\n params={\"q\": input_data[\"query\"]},\n headers={\"Authorization\": f\"Bearer {credential_value}\"},\n)\nresult[\"results\"] = response.json()[\"items\"]\n"
}
}'
import requests
version_id = "{INTEGRATION_VERSION_ID}"
url = f"https://operator.opus.com/api/v1/integration/v/{version_id}/action"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"action": {
"name": "Search Documents",
"description": "Search the Acme document index",
"endpoint": "https://api.acme.com/v1/search",
"inputs": {
"query": {
"id": "1",
"variableName": "query",
"displayName": "Query",
"description": "What to search for",
"isNullable": False,
"allowedTypes": [{"type": "str"}],
}
},
"outputs": {
"results": {
"id": "1",
"variableName": "results",
"displayName": "Results",
"allowedTypes": [{"type": "array"}],
}
},
"code": (
"import requests\n"
"response = requests.get(\n"
' "https://api.acme.com/v1/search",\n'
' params={"q": input_data["query"]},\n'
' headers={"Authorization": f"Bearer {credential_value}"},\n'
")\n"
'result["results"] = response.json()["items"]\n'
),
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const versionId = "{INTEGRATION_VERSION_ID}";
const response = await fetch(
`https://operator.opus.com/api/v1/integration/v/${versionId}/action`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
action: {
name: "Search Documents",
description: "Search the Acme document index",
endpoint: "https://api.acme.com/v1/search",
inputs: {
query: {
id: "1",
variableName: "query",
displayName: "Query",
description: "What to search for",
isNullable: false,
allowedTypes: [{ type: "str" }],
},
},
outputs: {
results: {
id: "1",
variableName: "results",
displayName: "Results",
allowedTypes: [{ type: "array" }],
},
},
code: [
"import requests",
"response = requests.get(",
' "https://api.acme.com/v1/search",',
' params={"q": input_data["query"]},',
' headers={"Authorization": f"Bearer {credential_value}"},',
")",
'result["results"] = response.json()["items"]',
].join("\n"),
},
}),
}
);
const data = await response.json();
console.log(data);
{
"actionId": "{ACTION_ID}",
"actionVersionId": "{ACTION_VERSION_ID}"
}
Add a single action to an integration you have already created.
Create an Integration accepts
actions[] inline, which covers authoring everything in one call. Use this endpoint instead when the integration already exists — to extend it with a new capability, or to add actions one at a time rather than batching them.
The body is the same action shape that endpoint accepts inline, so an action you can create one way you can create the other.
Use the versionId returned by Create an Integration as {integrationVersionId}.
Requires the Integration: Full permission at organization level.
Every call creates a new action. It never updates or replaces an existing one, even if the
name matches — call it twice and the integration has two actions.Headers
Path Parameters
The integration version to attach the action to. This is
versionId from Create an Integration — not the integration’s id.Body Parameters
The action is nested under anaction key.
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. Send {} for an action that takes no input.The action’s output schema, keyed by each field’s
variableName. Same shape as inputs. Send {} for an action that returns nothing.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.The field is
code. Unrecognised fields are dropped silently rather than rejected, so sending arb_code — the name used by the internal API — returns 201 with an action that has no code at all, and the action does nothing when a workflow runs it.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 created action version id. Every edit to an action creates a new version, so this identifies the exact revision you just authored.
Errors
Invalid body — a missing required field, a value over its limit, or an
integrationVersionId that is not a UUID.Your organization is not verified to author integrations, the key owner lacks the Integration: Full permission, or the integration belongs to another organization.
The integration version does not exist. Check you are using
versionId and not the integration’s id.curl --request POST \
--url https://operator.opus.com/api/v1/integration/v/{INTEGRATION_VERSION_ID}/action \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"action": {
"name": "Search Documents",
"description": "Search the Acme document index",
"endpoint": "https://api.acme.com/v1/search",
"inputs": {
"query": {
"id": "1",
"variableName": "query",
"displayName": "Query",
"description": "What to search for",
"isNullable": false,
"allowedTypes": [{ "type": "str" }]
}
},
"outputs": {
"results": {
"id": "1",
"variableName": "results",
"displayName": "Results",
"allowedTypes": [{ "type": "array" }]
}
},
"code": "import requests\nresponse = requests.get(\n \"https://api.acme.com/v1/search\",\n params={\"q\": input_data[\"query\"]},\n headers={\"Authorization\": f\"Bearer {credential_value}\"},\n)\nresult[\"results\"] = response.json()[\"items\"]\n"
}
}'
import requests
version_id = "{INTEGRATION_VERSION_ID}"
url = f"https://operator.opus.com/api/v1/integration/v/{version_id}/action"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"action": {
"name": "Search Documents",
"description": "Search the Acme document index",
"endpoint": "https://api.acme.com/v1/search",
"inputs": {
"query": {
"id": "1",
"variableName": "query",
"displayName": "Query",
"description": "What to search for",
"isNullable": False,
"allowedTypes": [{"type": "str"}],
}
},
"outputs": {
"results": {
"id": "1",
"variableName": "results",
"displayName": "Results",
"allowedTypes": [{"type": "array"}],
}
},
"code": (
"import requests\n"
"response = requests.get(\n"
' "https://api.acme.com/v1/search",\n'
' params={"q": input_data["query"]},\n'
' headers={"Authorization": f"Bearer {credential_value}"},\n'
")\n"
'result["results"] = response.json()["items"]\n'
),
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const versionId = "{INTEGRATION_VERSION_ID}";
const response = await fetch(
`https://operator.opus.com/api/v1/integration/v/${versionId}/action`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
action: {
name: "Search Documents",
description: "Search the Acme document index",
endpoint: "https://api.acme.com/v1/search",
inputs: {
query: {
id: "1",
variableName: "query",
displayName: "Query",
description: "What to search for",
isNullable: false,
allowedTypes: [{ type: "str" }],
},
},
outputs: {
results: {
id: "1",
variableName: "results",
displayName: "Results",
allowedTypes: [{ type: "array" }],
},
},
code: [
"import requests",
"response = requests.get(",
' "https://api.acme.com/v1/search",',
' params={"q": input_data["query"]},',
' headers={"Authorization": f"Bearer {credential_value}"},',
")",
'result["results"] = response.json()["items"]',
].join("\n"),
},
}),
}
);
const data = await response.json();
console.log(data);
{
"actionId": "{ACTION_ID}",
"actionVersionId": "{ACTION_VERSION_ID}"
}
Was this page helpful?