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

# Use your own IDs

> Give agents and objectives identifiers from your system, then use external_id references across SDK and API paths.

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:

```text theme={null}
support-bot
```

<Frame caption="An agent External ID set from the dashboard">
  <img src="https://mintcdn.com/cadenya/uaQ7Uw3TsXMwadaa/images/docs/ids/external-id-field.webp?fit=max&auto=format&n=uaQ7Uw3TsXMwadaa&q=85&s=2ab1918d0ed5ab6b7141a36e6c051468" alt="Agent metadata fields with Support Agent as the name and support-bot as the External ID" width="1384" height="588" data-path="images/docs/ids/external-id-field.webp" />
</Frame>

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:

```text theme={null}
ticket-4821
```

<Frame caption="An objective External ID from your application">
  <img src="https://mintcdn.com/cadenya/uaQ7Uw3TsXMwadaa/images/docs/objectives/external-id-field.webp?fit=max&auto=format&n=uaQ7Uw3TsXMwadaa&q=85&s=6af0003b7371a73e680e6f5d4344afb3" alt="New Objective Metadata section with ticket-4821 as the External ID" width="1384" height="496" data-path="images/docs/objectives/external-id-field.webp" />
</Frame>

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:

```typescript theme={null}
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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const objective = await client.objectives.retrieve(
    'external_id:ticket-4821',
    { workspaceId },
  );

  console.log(objective.state);
  ```

  ```bash cURL theme={null}
  curl \
    "https://api.cadenya.com/v1/workspaces/${CADENYA_WORKSPACE_ID}/objectives/external_id:ticket-4821" \
    -H "Authorization: Bearer ${CADENYA_API_KEY}"
  ```
</CodeGroup>

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

```typescript theme={null}
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:

```text theme={null}
/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:

```typescript theme={null}
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.

<CardGroup cols={2}>
  <Card title="Run your first objective" icon="play" href="/docs/guides/run-an-objective">
    Create and inspect the run in the dashboard.
  </Card>

  <Card title="Objectives from the SDK" icon="code" href="/docs/guides/sdk/objectives">
    Continue, cancel, stream, and score by either identifier form.
  </Card>

  <Card title="Approving a tool" icon="hand" href="/docs/guides/callbacks/approving-a-tool">
    Route an approval request using objective metadata.
  </Card>

  <Card title="API design" icon="fingerprint" href="/docs/guides/api-design#external-ids-are-first-class-in-paths">
    Review external-ID scoping and path-resolution rules.
  </Card>
</CardGroup>