Create a Code Node

curl --request POST \
  --url https://operator.opus.com/api/v1/code \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: {YOUR_SERVICE_KEY}' \
  --data '{
    "code": {
      "name": "Normalize Text",
      "description": "Collapses runs of whitespace in OCR output",
      "icon": "{BASE64_ICON}",
      "sourceCode": "import re\n\n\ndef main(inputs):\n    raw_text = inputs.get(\"raw_text\") or \"\"\n\n    return {\"clean_text\": re.sub(r\"\\s+\", \" \", raw_text).strip()}\n",
      "categories": ["text_processing"],
      "inputs": {
        "raw_text": {
          "id": "1",
          "variableName": "raw_text",
          "displayName": "Raw Text",
          "allowedTypes": [{ "type": "str" }]
        }
      },
      "outputs": {
        "clean_text": {
          "id": "1",
          "variableName": "clean_text",
          "displayName": "Clean Text",
          "allowedTypes": [{ "type": "str" }]
        }
      }
    }
  }'

import requests

url = "https://operator.opus.com/api/v1/code"
headers = {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}"
}
source = '''import re


def main(inputs):
    raw_text = inputs.get("raw_text") or ""

    return {"clean_text": re.sub(r"\\s+", " ", raw_text).strip()}
'''
payload = {
    "code": {
        "name": "Normalize Text",
        "description": "Collapses runs of whitespace in OCR output",
        "icon": "{BASE64_ICON}",
        "sourceCode": source,
        "categories": ["text_processing"],
        "inputs": {
            "raw_text": {
                "id": "1",
                "variableName": "raw_text",
                "displayName": "Raw Text",
                "allowedTypes": [{"type": "str"}],
            }
        },
        "outputs": {
            "clean_text": {
                "id": "1",
                "variableName": "clean_text",
                "displayName": "Clean Text",
                "allowedTypes": [{"type": "str"}],
            }
        },
    }
}

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

const source = `import re


def main(inputs):
    raw_text = inputs.get("raw_text") or ""

    return {"clean_text": re.sub(r"\\s+", " ", raw_text).strip()}
`;

const response = await fetch("https://operator.opus.com/api/v1/code", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}",
  },
  body: JSON.stringify({
    code: {
      name: "Normalize Text",
      description: "Collapses runs of whitespace in OCR output",
      icon: "{BASE64_ICON}",
      sourceCode: source,
      categories: ["text_processing"],
      inputs: {
        raw_text: {
          id: "1",
          variableName: "raw_text",
          displayName: "Raw Text",
          allowedTypes: [{ type: "str" }],
        },
      },
      outputs: {
        clean_text: {
          id: "1",
          variableName: "clean_text",
          displayName: "Clean Text",
          allowedTypes: [{ type: "str" }],
        },
      },
    },
  }),
});

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

{
  "id": "{CODE_ID}",
  "name": "Normalize Text",
  "description": "Collapses runs of whitespace in OCR output",
  "versionId": "{CODE_VERSION_ID}"
}

POST

api

code

curl --request POST \
  --url https://operator.opus.com/api/v1/code \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: {YOUR_SERVICE_KEY}' \
  --data '{
    "code": {
      "name": "Normalize Text",
      "description": "Collapses runs of whitespace in OCR output",
      "icon": "{BASE64_ICON}",
      "sourceCode": "import re\n\n\ndef main(inputs):\n    raw_text = inputs.get(\"raw_text\") or \"\"\n\n    return {\"clean_text\": re.sub(r\"\\s+\", \" \", raw_text).strip()}\n",
      "categories": ["text_processing"],
      "inputs": {
        "raw_text": {
          "id": "1",
          "variableName": "raw_text",
          "displayName": "Raw Text",
          "allowedTypes": [{ "type": "str" }]
        }
      },
      "outputs": {
        "clean_text": {
          "id": "1",
          "variableName": "clean_text",
          "displayName": "Clean Text",
          "allowedTypes": [{ "type": "str" }]
        }
      }
    }
  }'

import requests

url = "https://operator.opus.com/api/v1/code"
headers = {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}"
}
source = '''import re


def main(inputs):
    raw_text = inputs.get("raw_text") or ""

    return {"clean_text": re.sub(r"\\s+", " ", raw_text).strip()}
'''
payload = {
    "code": {
        "name": "Normalize Text",
        "description": "Collapses runs of whitespace in OCR output",
        "icon": "{BASE64_ICON}",
        "sourceCode": source,
        "categories": ["text_processing"],
        "inputs": {
            "raw_text": {
                "id": "1",
                "variableName": "raw_text",
                "displayName": "Raw Text",
                "allowedTypes": [{"type": "str"}],
            }
        },
        "outputs": {
            "clean_text": {
                "id": "1",
                "variableName": "clean_text",
                "displayName": "Clean Text",
                "allowedTypes": [{"type": "str"}],
            }
        },
    }
}

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

const source = `import re


def main(inputs):
    raw_text = inputs.get("raw_text") or ""

    return {"clean_text": re.sub(r"\\s+", " ", raw_text).strip()}
`;

const response = await fetch("https://operator.opus.com/api/v1/code", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}",
  },
  body: JSON.stringify({
    code: {
      name: "Normalize Text",
      description: "Collapses runs of whitespace in OCR output",
      icon: "{BASE64_ICON}",
      sourceCode: source,
      categories: ["text_processing"],
      inputs: {
        raw_text: {
          id: "1",
          variableName: "raw_text",
          displayName: "Raw Text",
          allowedTypes: [{ type: "str" }],
        },
      },
      outputs: {
        clean_text: {
          id: "1",
          variableName: "clean_text",
          displayName: "Clean Text",
          allowedTypes: [{ type: "str" }],
        },
      },
    },
  }),
});

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

{
  "id": "{CODE_ID}",
  "name": "Normalize Text",
  "description": "Collapses runs of whitespace in OCR output",
  "versionId": "{CODE_VERSION_ID}"
}

Register a Python code node in the marketplace under your organization. The node is authored at the organization level, so it is not bound to a workspace and is not runnable until it is connected into one. Returns the code id, which you pass to Update a Code Node. Requires the Code: Full permission at organization level, and a verified organization.

There is no provider call to make first. Your organization’s code provider is resolved for you, and providerId is not accepted in the body.

Headers

string

required

Your API authentication key

Body Parameters

The code node is nested under a code key.

object

required

The code node to create. Fields below.

string

required

Code node display name. Maximum 255 characters.

string

required

What the code does, shown under its name. Maximum 2048 characters.

string

required

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

string

required

The Python source the node runs. Must define main(inputs). Maximum 262144 bytes when UTF-8 encoded. See Writing the source.

string[]

required

Categories the code node is filed under in the marketplace. Maximum 5 entries. See Categories.

object

The node’s input schema, keyed by each variable’s variableName. Maximum 100 entries and 512KB JSON-encoded. See Variable object.

object

The node’s output schema, keyed by each variable’s variableName. Same shape and limits as inputs.

string

default:"active"

Code status — active, inactive, soon or deprecated.

boolean

default:"true"

Show the “new” badge on the code tile.

boolean

default:"false"

Show the “popular” badge on the code tile.

boolean

default:"false"

Show the “beta” badge on the code tile.

Your organization is always taken from the API key — it cannot be set in the body. Nothing here is workspace-scoped. Fields the API does not recognise, including providerId, are dropped rather than rejected.

Variable object

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

string

required

Stable identifier for the variable, unique within the schema. Maximum 255 characters.

string

required

Programmatic key. Must equal the key this entry sits under. This is the key your code reads out of the inputs dictionary, or returns in the result dictionary, so it follows Python naming rather than camelCase. Maximum 255 characters.

object[]

required

Value types this variable 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

Human-readable label rendered in the workflow builder. Maximum 255 characters. When omitted, the code service applies its own default.

string

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

any

default:"null"

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

boolean

default:"false"

When true, the workflow may leave this variable unset.

object[]

Annotations the builder uses for grouping and filtering, each { variableName, value, description }. Maximum 20.

any[]

Enum-style choice list. When non-empty the builder renders a dropdown. Each entry is free-form JSON. Maximum 20.

string

Which of allowedTypes is currently active. Must be one of them — consumers fall back to the first entry when unset.

string[]

Fields the builder locks, preventing the workflow author from changing them — any of variable_name, display_name, description, is_nullable, tags, options, allowed_types. Maximum 20.

boolean

default:"true"

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

For composite types, typeDefinition describes the shape inside: a nested variable map for object, a single nested variable for array, or a date format string for date. Omit it for scalars. Set typeDefinitionEnforced to hold the workflow author to it exactly.

Response

string

required

The code id. Pass it as {codeId} to Update a Code Node. There is no endpoint to look this up again — store it.

string

required

Code node display name.

string

Code node description.

string

Id of the version this call created.

The response echoes only these four fields. icon, categories, status and the badge flags are stored but not returned.

Errors

Bad Request

Invalid body — a missing required field, a value over its limit, more than 5 categories, an unrecognised category or status, an inputs/outputs entry that is not a valid variable, or source that failed the security scan. A scan failure carries a violations array.

Unauthorized

Missing, invalid, or expired API key.

Forbidden

Your organization is not verified to author code, the API key is not org-scoped, or the key owner lacks the Code: Full permission in the organization.

curl --request POST \
  --url https://operator.opus.com/api/v1/code \
  --header 'Content-Type: application/json' \
  --header 'x-service-key: {YOUR_SERVICE_KEY}' \
  --data '{
    "code": {
      "name": "Normalize Text",
      "description": "Collapses runs of whitespace in OCR output",
      "icon": "{BASE64_ICON}",
      "sourceCode": "import re\n\n\ndef main(inputs):\n    raw_text = inputs.get(\"raw_text\") or \"\"\n\n    return {\"clean_text\": re.sub(r\"\\s+\", \" \", raw_text).strip()}\n",
      "categories": ["text_processing"],
      "inputs": {
        "raw_text": {
          "id": "1",
          "variableName": "raw_text",
          "displayName": "Raw Text",
          "allowedTypes": [{ "type": "str" }]
        }
      },
      "outputs": {
        "clean_text": {
          "id": "1",
          "variableName": "clean_text",
          "displayName": "Clean Text",
          "allowedTypes": [{ "type": "str" }]
        }
      }
    }
  }'

import requests

url = "https://operator.opus.com/api/v1/code"
headers = {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}"
}
source = '''import re


def main(inputs):
    raw_text = inputs.get("raw_text") or ""

    return {"clean_text": re.sub(r"\\s+", " ", raw_text).strip()}
'''
payload = {
    "code": {
        "name": "Normalize Text",
        "description": "Collapses runs of whitespace in OCR output",
        "icon": "{BASE64_ICON}",
        "sourceCode": source,
        "categories": ["text_processing"],
        "inputs": {
            "raw_text": {
                "id": "1",
                "variableName": "raw_text",
                "displayName": "Raw Text",
                "allowedTypes": [{"type": "str"}],
            }
        },
        "outputs": {
            "clean_text": {
                "id": "1",
                "variableName": "clean_text",
                "displayName": "Clean Text",
                "allowedTypes": [{"type": "str"}],
            }
        },
    }
}

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

const source = `import re


def main(inputs):
    raw_text = inputs.get("raw_text") or ""

    return {"clean_text": re.sub(r"\\s+", " ", raw_text).strip()}
`;

const response = await fetch("https://operator.opus.com/api/v1/code", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-service-key": "{YOUR_SERVICE_KEY}",
  },
  body: JSON.stringify({
    code: {
      name: "Normalize Text",
      description: "Collapses runs of whitespace in OCR output",
      icon: "{BASE64_ICON}",
      sourceCode: source,
      categories: ["text_processing"],
      inputs: {
        raw_text: {
          id: "1",
          variableName: "raw_text",
          displayName: "Raw Text",
          allowedTypes: [{ type: "str" }],
        },
      },
      outputs: {
        clean_text: {
          id: "1",
          variableName: "clean_text",
          displayName: "Clean Text",
          allowedTypes: [{ type: "str" }],
        },
      },
    },
  }),
});

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

{
  "id": "{CODE_ID}",
  "name": "Normalize Text",
  "description": "Collapses runs of whitespace in OCR output",
  "versionId": "{CODE_VERSION_ID}"
}

Get Started

Workflows

Cases

Files

Business Process Discovery

Integrations

Code

Agents

Deprecated

Create a Code Node

Headers

Body Parameters

Variable object

Categories

Response

Errors

​Headers

​Body Parameters

​Variable object

​Categories

​Response

​Errors

Headers

Body Parameters

Variable object

Categories

Response

Errors