Use your own IDs

Cadenya assigns canonical IDs such as agent_... and obj_.... You can also set an external ID from your own system and address the resource as external_id:<value>. This lets a ticket number, workflow key, or database ID remain the handle your application stores.

Add an external ID to an agent

Open a draft agent, select Actions → Edit, and expand Add labels or external ID. Set External ID to:

support-bot

Agent metadata fields with Support Agent as the name and support-bot as the External ID — An agent External ID set from the dashboard

Save the agent and publish it. The Details card now displays and copies support-bot. An agent external ID is unique within its workspace. Cadenya rejects a second agent that tries to use the same value.

Create an objective with your ID

Open Objectives and select New Objective. Choose the published agent and enter a first user message. Expand Add labels or external ID, then set External ID to a value from your application:

ticket-4821

New Objective Metadata section with ticket-4821 as the External ID — An objective External ID from your application

Select Create Objective. The objective’s Details card records the external ID next to its canonical ID and configuration snapshot. Use labels for filterable categories, such as team=support. Use the external ID for one unique application-level identity.

Dispatch by the agent’s external ID

Pass the prefixed agent reference anywhere an agent ID is accepted:

const objective = await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support-bot',
  metadata: {
    externalId: 'ticket-4821',
    labels: {
      source: 'support',
    },
  },
  systemPromptData: {},
  firstUserMessage: 'A customer cannot log in.',
});

The response still returns Cadenya’s canonical ID in objective.metadata.id. Your value appears in objective.metadata.externalId.

Retrieve by your objective ID

Use the same prefix on reads and actions:

const objective = await client.objectives.retrieve(
  'external_id:ticket-4821',
  { workspaceId },
);

console.log(objective.state);

curl \
  "https://api.cadenya.com/v1/workspaces/${CADENYA_WORKSPACE_ID}/objectives/external_id:ticket-4821" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}"

The prefixed objective reference also works with continuation, cancellation, feedback, event listing, and event streaming:

await client.objectives.continue('external_id:ticket-4821', {
  workspaceId,
  message: 'Ask whether password reset email is blocked.',
});

Use external IDs in nested paths

Every resolvable path segment can choose its own identifier form:

/v1/workspaces/external_id:production
  /agents/external_id:support-bot
  /variations/external_id:concise

Top-level resources scope their external IDs to the workspace. Child resources scope them to their parent, so two different agents can each have a variation named external_id:concise. Join records such as variation assignments do not define external IDs. Address those rows by the canonical ID returned when they are created.

Route webhooks without a lookup

Every objective webhook includes the objective operation metadata:

const objective = event.data.objective;

console.log({
  cadenyaId: objective.id,
  ticket: objective.externalId,
  labels: objective.labels,
});

Set the external ID to your application record and webhook handlers can route an event directly without maintaining a Cadenya-ID lookup table.

Run your first objective

Create and inspect the run in the dashboard.

Objectives from the SDK

Continue, cancel, stream, and score by either identifier form.

Approving a tool

Route an approval request using objective metadata.

API design

Review external-ID scoping and path-resolution rules.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Use your own IDs

Add an external ID to an agent

Create an objective with your ID

Dispatch by the agent’s external ID

Retrieve by your objective ID

Use external IDs in nested paths

Route webhooks without a lookup

Run your first objective

Objectives from the SDK

Approving a tool

API design

​Add an external ID to an agent

​Create an objective with your ID

​Dispatch by the agent’s external ID

​Retrieve by your objective ID

​Use external IDs in nested paths

​Route webhooks without a lookup

Run your first objective

Objectives from the SDK

Approving a tool

API design

Add an external ID to an agent

Create an objective with your ID

Dispatch by the agent’s external ID

Retrieve by your objective ID

Use external IDs in nested paths

Route webhooks without a lookup