Corezoid Alias Manager

Corezoid Alias Manager

What aliases are

An alias is a human-readable short_name (e.g. payment-service, send-otp) that maps to a process (conv). Aliases serve two purposes:

1. Process reference in JSON — use @alias-name as conv_id instead of a numeric process ID. This makes processes portable across environments and removes hardcoded IDs.
2. External HTTP entry point — each alias generates a callback_hash used to send tasks to the process via the API Gateway URL.

Alias naming rules (same as Corezoid short names):

• Only lowercase letters [a-z], digits [0-9], and hyphens -
• Must be at least 3 characters
• Must be unique within the stage
• Good: payment-checkout, send-otp, create-user-v2
• Bad: MyAlias, PAYMENT, a

MCP Tools

Note: modify, delete, and unlink operations are not yet exposed as MCP tools. Use the direct API calls documented below to perform them.

Using aliases in process JSON

Once an alias exists, replace the numeric conv_id with @alias-name in any node that calls another process:

Call a Process node (api_rpc)

jsonCopy code
{
  "type": "api_rpc",
  "conv_id": "@payment-checkout",
  "extra": { "amount": "{{amount}}", "currency": "{{currency}}" },
  "extra_type": { "amount": "number", "currency": "string" },
  "err_node_id": "<error_node_id>"
}

Copy Task node (api_copy)

jsonCopy code
{
  "type": "api_copy",
  "conv_id": "@send-notification",
  "ref": "{{unique_ref}}",
  "mode": "create",
  "err_node_id": "<error_node_id>"
}

State store read in set_param or condition

Copy code
{{conv[@user-states].ref[{{task_ref}}].status}}

This reads the status field of the task with reference {{task_ref}} from the @user-states state diagram process.

Workflow: Create an alias

Step 1 — Resolve the process

Check whether the user provided a file path, process name, or process ID. If a file path is given, the process ID is the leading number in the filename (e.g. 1834583_My_Process.conv.json → process_id = 1834583).

If only a name is given, search locally:

bashCopy code
find . -name "*.conv.json" | xargs grep -l '"title": "My Process"'

Step 2 — Check if the alias already exists

Before creating, verify the short_name is not taken. Call the list aliases API (see "Workflow: List aliases" below) and scan the short_name fields. If a conflict is found, suggest an alternative name to the user.

Step 3 — Decide the short_name

Apply the naming rules: lowercase, hyphens, no spaces or underscores, at least 3 chars. Suggest a name derived from the process title if the user hasn't specified one.

Step 4 — Create the alias

Call MCP tool create-alias with:

• process_path: relative path to the .conv.json file
• short_name: the alias short name

Copy code
create-alias(
  process_path="./671255_develop/1834583_My_Process.conv.json",
  short_name="payment-checkout"
)

The tool creates the alias, links it to the process, and returns the alias_id. Requires a <id>_<name>.stage.json marker at the workspace root (run corezoid-init if missing).

Step 5 — Update and redeploy referencing processes

After creating the alias, replace any numeric conv_id references to this process across the project with @short-name:

bashCopy code
grep -rl '"conv_id": 1834583' . --include="*.conv.json"

For each file found, replace "conv_id": 1834583 with "conv_id": "@payment-checkout". Then for each modified file, run lint-process and on success push-process.

After pushing, tell the user: "Changes deployed. Please refresh the page in Corezoid to see the updated process."

Workflow: List aliases

Call cz-structure with action list-aliases:

Copy code
cz-structure {"action": "list-aliases", "args": {
  "company_id": "<WORKSPACE_ID>",
  "project_id": <PROJECT_ID>,
  "stage_id": <STAGE_ID>,
  "short_name": "<optional: filter to one exact alias>"
}}

company_id, project_id and stage_id identify the project/stage to search — resolve them with list-projects/list-stages (cz-structure) when searching a stage other than the one currently configured. Pass short_name when you already know the alias you need (e.g. resolving a receiver by name) to get a one-line answer instead of the full table.

Returned per alias:

Workflow: Modify an alias

To rename an alias or change its title/description (does NOT change which process it points to — use unlink + link for that).

API call:

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type": "modify",
    "obj": "alias",
    "obj_id": <ALIAS_ID>,
    "title": "New Display Title",
    "short_name": "new-short-name",
    "description": "Updated description",
    "company_id": "<WORKSPACE_ID>",
    "project_id": <PROJECT_ID>,
    "stage_id": <STAGE_ID>
  }]
}

⚠️ Changing short_name invalidates all "conv_id": "@old-name" references across every process in the project. Grep all .conv.json files and update them, then push each modified process.

Workflow: Repoint an alias to a different process

Use two API calls: unlink from the current process, then link to the new one.

Step 1 — Unlink from current process

Copy code
POST {corezoid_url}/api/2/json

{
  "ops": [{
    "type": "link",
    "obj": "alias",
    "link": false,
    "obj_id": <ALIAS_ID>,
    "obj_to_id": <CURRENT_PROCESS_ID>,
    "obj_to_type": "conv",
    "company_id": "<WORKSPACE_ID>"
  }]
}

Step 2 — Link to new process

Copy code
POST {corezoid_url}/api/2/json

{
  "ops": [{
    "type": "link",
    "obj": "alias",
    "link": true,
    "obj_id": <ALIAS_ID>,
    "obj_to_id": <NEW_PROCESS_ID>,
    "obj_to_type": "conv",
    "company_id": "<WORKSPACE_ID>"
  }]
}

Workflow: Delete an alias

⚠️ Before deleting, check all .conv.json files for "conv_id": "@alias-name" references. Deleting an alias breaks every process that uses it.

API call:

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type": "delete",
    "obj": "alias",
    "obj_id": <ALIAS_ID>,
    "company_id": "<WORKSPACE_ID>"
  }]
}

After deletion, replace all "conv_id": "@alias-name" references with the numeric process ID (or create a new alias), then push each affected process.

Workflow: Get callback hash (external task submission URL / Direct URL webhook)

The callback hash is the secret in a process's or alias's Direct URL — the public webhook endpoint external systems POST tasks to. A process and each of its aliases have independent hashes; rotating or deleting one does not affect the others.

Get the hash — by process (conv_id):

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type": "get",
    "obj": "callback_hash",
    "conv_id": <PROCESS_ID>,
    "company_id": "<WORKSPACE_ID>"
  }]
}

Get the hash — by alias (alias_id):

Copy code
POST {corezoid_url}/api/2/json
Authorization: Simulator {access_token}
Content-Type: application/json

{
  "ops": [{
    "type": "get",
    "obj": "callback_hash",
    "obj_type": "alias",
    "alias_id": <ALIAS_ID>,
    "company_id": "<WORKSPACE_ID>"
  }]
}

Response (both):

jsonCopy code
{ "request_proc": "ok", "ops": [{ "proc": "ok", "callback_hash": "19e339a865d676db68b776f440443821c49a0e30" }] }

Other type values on the same obj: "callback_hash" (swap "type": "get" for one of these, keeping the same conv_id/alias_id field):

External submission URL:

⚠️ The URL format is installation-specific — always verify against the Direct URL shown in the Corezoid UI for that process/alias before handing it to another system. Two formats have been observed:

• Cloud (dedicated API Gateway):

  Copy code
  POST {COREZOID_APIGW_URL}/api/1/json/<WORKSPACE_ID>/<callback_hash>
  Content-Type: application/json
  
  { "ops": [{ "ref": "unique-task-ref", "type": "create", "obj": "task", "data": { "key": "value" } }] }
  

  Where COREZOID_APIGW_URL defaults to https://api-apigw.corezoid.com.

• Self-hosted (served off the same account host, no separate gateway):

  Copy code
  By conv_id:  https://<host>/api/2/json/public/<conv_id>/<callback_hash>
  By alias:    https://<host>/api/2/json/public/@<alias_short_name>/<project_short_name>/<stage_short_name>/<company_id>/<callback_hash>
  

  <host> is the same host as corezoid_url on the current Folder. Some installations serve this under /api/1/json/public/... instead of /api/2/ — don't assume without confirming once per installation.

Either way, the hash in the URL is the authentication — treat it like a secret. Prefer alias-based URLs for anything referenced by external systems: an alias can be re-pointed at a new process without invalidating URLs already handed out.

Resolving environment values

create-alias resolves stage_id/project_id automatically from the target process's own location — no argument needed. list-aliases (cz-structure) does not: it takes project_id/stage_id/company_id explicitly, because it is meant to look up aliases in any stage, not only the one currently configured. For direct /api/2/json calls (the raw workflows above) collect the values from:

If the marker file is missing, run the corezoid-init skill.

Two-step create (alternative manual flow)

The create-alias MCP tool creates and links in a single request. If you need finer control (create first, link later), use the two-step API flow:

Step 1 — Create the alias object

jsonCopy code
{
  "ops": [{
    "type": "create",
    "obj": "alias",
    "title": "My Alias Title",
    "short_name": "my-alias",
    "description": "",
    "company_id": "<WORKSPACE_ID>",
    "project_id": <PROJECT_ID>,
    "stage_id": <STAGE_ID>
  }]
}

Response: { "obj_id": <ALIAS_ID>, "proc": "ok" }

Step 2 — Link the alias to a process

jsonCopy code
{
  "ops": [{
    "type": "link",
    "obj": "alias",
    "link": true,
    "obj_id": <ALIAS_ID>,
    "obj_to_id": <PROCESS_ID>,
    "obj_to_type": "conv",
    "company_id": "<WORKSPACE_ID>"
  }]
}

Common pitfalls

Decision guide

Reference Documents