> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an Action

> Add an action to an integration that already exists

Add a single action to an integration you have already created.

[Create an Integration](https://developer.opus.com/api-reference/v1-integration/create-integration.md) 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](https://developer.opus.com/api-reference/v1-integration/create-integration.md) as `{integrationVersionId}`.

Requires the **Integration: Full** permission at organization level.

> [!NOTE]
>
> 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

**x-service-key** `string` *required*

Your API authentication key

## Path Parameters

**integrationVersionId** `string` *required*

The integration version to attach the action to. This is `versionId` from [Create an Integration](https://developer.opus.com/api-reference/v1-integration/create-integration.md) — not the integration's `id`.

## Body Parameters

The action is nested under an `action` key.

**action** `object` *required*

The action to create. Fields below.

**action.name** `string` *required*

Action name, shown in the workflow builder. Maximum 255 characters.

**action.endpoint** `string` *required*

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

**action.inputs** `object` *required*

The action's input schema, keyed by each field's `variableName`. See [Field object](#field-object). Send `{}` for an action that takes no input.

**action.outputs** `object` *required*

The action's output schema, keyed by each field's `variableName`. Same shape as `inputs`. Send `{}` for an action that returns nothing.

**action.description** `string`

Action description. Maximum 2048 characters.

**action.code** `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.

> [!WARNING]
>
> 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 inside `inputs` and `outputs`. The map key must equal the field's `variableName`.

**id** `string` *required*

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

**variableName** `string` *required*

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

**displayName** `string` *required*

Human-readable label rendered in the workflow builder.

**allowedTypes** `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`.

**description** `string`

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

**default** `any`

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

**isNullable** `boolean` (default: false)

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

**tags** `string[]`

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

**options** `object[]`

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

**nonEditableFields** `string[]`

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

**canDelete** `boolean` (default: true)

When false, the builder hides the "remove field" affordance.

> [!NOTE]
>
> 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

**actionId** `string` *required*

The created action id.

**actionVersionId** `string` *required*

The created action version id. Every edit to an action creates a new version, so this identifies the exact revision you just authored.

## Errors

**400** `Bad Request`

Invalid body — a missing required field, a value over its limit, or an `integrationVersionId` that is not a UUID.

**401** `Unauthorized`

Missing, invalid, or expired API key.

**403** `Forbidden`

Your organization is not verified to author integrations, the key owner lacks the **Integration: Full** permission, or the integration belongs to another organization.

**404** `Not Found`

The integration version does not exist. Check you are using `versionId` and not the integration's `id`.

**422** `Unprocessable Entity`

Rejected downstream after passing validation here.

```bash cURL theme={null}
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"
    }
  }'
```

```python Python theme={null}
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())
```

```javascript JavaScript theme={null}
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);
```

```json 201 Response theme={null}
{
  "actionId": "{ACTION_ID}",
  "actionVersionId": "{ACTION_VERSION_ID}"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.