Skip to navigation
API fundamentals

Resource keys

Your own stable name for a piece of configuration.

Agents, MCP servers, Knowledge sources and secrets accept an optional resource_key when you create them. It lets a setup script find its own configuration again on the next run.

  • Syntax: ^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}$. A UUID is valid.

  • It is set at creation only. A different key on a later update answers 409 conflict with details.reason: resource_key_immutable; leaving it out of a PUT keeps the stored key.

  • It is unique per resource type within the workspace. A duplicate create answers 409 resource_key_conflict, and details.existing_id names the resource that already has it.

  • Archiving does not free a key. A key is freed only when its resource is erased, destroyed or permanently deleted.

  • An MCP server disabled through the API or app keeps its key. Creating a server with that key answers 409 resource_key_conflict, naming a server the API no longer shows.

  • Tools have no resource key: a tool’s name is its key within the agent’s draft. Calls have none.

Find your configuration again

List operations take a repeated resource_key filter:

curl -sS "$RASEN_API_BASE/agents?resource_key=support-line" -H "Authorization: Bearer $RASEN_API_KEY"
curl -sS "$RASEN_API_BASE/secrets?resource_key=crm-prod" -H "Authorization: Bearer $RASEN_API_KEY"

A resource_key lookup of agents also finds an archived agent.

A typical setup script looks the key up first, and creates the resource only when the lookup is empty. If a create answers 409 resource_key_conflict, read details.existing_id and reconcile.

Not an idempotency key

A resource key names configuration across runs. An Idempotency-Key protects one request against a lost answer. Use both: a resource key to find your agent, and a new idempotency key for each create or edit. See Idempotency and replay.