> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors.md).

# Dynamic Behaviors

Create dynamic behavior sets and versions, pin a version on a service, move or clear a pin, and read which behavior a reply used, with limits and errors.

A workspace keeps its dynamic behaviors in a library of sets. Each set has numbered versions that cannot be edited. A service runs a behavior when its `release` version set pins one of its versions. This page covers the library operations, pinning, limits, and errors. [Dynamic Behaviors](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors) explains how behaviors are chosen and how long they stay, and [Author Dynamic Behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/authoring-dynamic-behaviors.md) covers how to write them.

The terms used below:

* A **set** is one behavior, with a name, optional tags, and numbered **versions**.
* A **version** holds a condition, examples, an instruction, a mode, sticky turns, and a note.
* A **version set** is a named configuration on a service. Calls and conversations run the service's `release` version set.
* A **pin** names a set, an exact version, whether it is enabled, and the states it applies in. A version set holds a list of pins.
* The **selector** is the model that chooses at most one behavior on each caller turn from the enabled pins that apply.

Writes need an `admin` or `owner` key. See [Permissions](#permissions). Library writes and the version set upsert allow 10 requests per minute for each credential and route, so a script that creates many sets backs off on `429`. See [Limits](#limits).

A typical sequence:

1. [Create a set](#create-a-set) with its first version.
2. [Write the next version](#write-the-next-version) whenever the behavior changes.
3. [Pin a version](#pin-a-version-on-a-service) on a test service's `release` version set, check it, then pin it on the live service.
4. [Read what applied](#read-what-applied) on conversations and calls.
5. [Move the pin back, or disable it](#move-disable-or-clear-a-pin), to roll back.
6. [Retire a set](#retire-a-set) that no service needs: clear its pins, then archive it.

## Create a Set <a href="#create-a-set" id="create-a-set"></a>

Creating a set stores the set and its version 1 in one request, and returns `201` with the set. `name` and `first_version` are required. The name is trimmed and must be unique among the workspace's sets that are not archived, ignoring case. Another workspace can use the same name.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

In `first_version`, `mode` defaults to `add`, `sticky_turns` to `1`, and `examples` to an empty list. `instruction` is optional: a version without one can be chosen and recorded, and it adds no guidance to the reply (see [What the Reply Follows](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors#what-the-reply-follows)). A `replace` version must have an instruction. Leave `id` out so the platform generates it. Setting it needs `platform:admin`, which workspace credentials do not carry.

### Example

```bash
curl -X POST "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing questions",
    "tags": ["billing"],
    "first_version": {
      "condition": "The caller has a question about a bill, a balance, a statement or a payment.",
      "examples": [
        "Why did I get a bill for my last visit?",
        "I think I was charged twice",
        "Can I set up a payment plan?"
      ],
      "instruction": "Keep answers short and in plain words. Ask which visit or statement the caller means before explaining a charge, and finish by saying what the next step is.",
      "sticky_turns": 2,
      "note": "First version"
    }
  }'
```

### Example Response

```json
{
  "id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
  "workspace_id": "c8e1f2a4-6b7d-4f3e-9a10-2b5d8c7e4f61",
  "name": "Billing questions",
  "tags": ["billing"],
  "latest_version": 1,
  "archived_at": null,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-10-26T14:05:11.482913Z",
  "updated_at": "2026-10-26T14:05:11.482913Z"
}
```

A set carries no version text. Read a version for the condition, examples, and instruction.

## Write the Next Version <a href="#write-the-next-version" id="write-the-next-version"></a>

A version cannot be edited. To change a behavior, write the next version. A version is written in full: read the latest version, change what you want, and send every field. A field you leave out takes its default (no instruction, `add` mode, `sticky_turns` of `1`, no examples), and nothing carries over from the previous version. Send `expected_latest_version`, the latest version number you read, so that two writers cannot overwrite each other. When the set is at a different version, the request returns `409` and stores nothing. Read the set, apply your change to its latest version, and send the request again. Of two writers racing on one set, exactly one succeeds.

No service runs the version until a version set pins it. `PUT`, `PATCH`, and `DELETE` on a version return `405`, and a set has no delete operation.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets/{set\_id}/versions" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

Read the latest version first. Versions come newest first, so `limit=1` returns it:

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}/versions?limit=1" \
  -H "Authorization: Bearer <api-key>"
```

Then write version 2 from it. `expected_latest_version` is the version you read, and the body carries every field of version 2:

```bash
curl -X POST "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}/versions?expected_latest_version=1" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "condition": "The caller has a question about a bill, a balance, a statement or a payment, or asks how to pay.",
    "examples": [
      "Why did I get a bill for my last visit?",
      "I think I was charged twice",
      "Can I set up a payment plan?",
      "How do I pay my balance?"
    ],
    "instruction": "Keep answers short and in plain words. Ask which visit or statement the caller means before explaining a charge, and finish by saying what the next step is.",
    "sticky_turns": 3,
    "note": "Added payment questions"
  }'
```

### Example Response

The response is `201` with version 2:

```json
{
  "set_id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
  "version": 2,
  "condition": "The caller has a question about a bill, a balance, a statement or a payment, or asks how to pay.",
  "examples": [
    "Why did I get a bill for my last visit?",
    "I think I was charged twice",
    "Can I set up a payment plan?",
    "How do I pay my balance?"
  ],
  "instruction": "Keep answers short and in plain words. Ask which visit or statement the caller means before explaining a charge, and finish by saying what the next step is.",
  "mode": "add",
  "sticky_turns": 3,
  "note": "Added payment questions",
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-10-26T14:22:40.108377Z"
}
```

## Pin a Version on a Service <a href="#pin-a-version-on-a-service" id="pin-a-version-on-a-service"></a>

A version set pins library behaviors in its `dynamic_behavior_sets` list. Each pin has:

* `set_id`: a set in the service's workspace that is not archived.
* `version`: the exact version the service runs.
* `enabled`: defaults to `true`. A disabled pin stays on the version set and is not offered to the selector.
* `states`: the action and data collection states the pin applies in. The default, an empty list, means every one.

Pins keep the order you send them in. The order can break a tie between behaviors that fit equally well, but it is not a priority, so settle overlap in the conditions. A reorder is a pin change and is sent to the audit log. See [Permissions](#permissions). A version set pins a set once.

{% hint style="warning" %}
**This changes what live callers get.** A pin on a service's `release` version set applies once calls and conversations load the service's configuration. See [Saving a Pin Applies It](#saving-a-pin-applies-it). Pin and check a behavior on a test service first. See [Test on a Test Service Before the Live One](https://docs.concurrence.com/developer-guide/platform-api/workspaces/authoring-dynamic-behaviors.md#test-on-a-test-service). To undo a pin, [disable or clear it](#move-disable-or-clear-a-pin). A set cannot be deleted. See [Retire a Set](#retire-a-set).
{% endhint %}

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}/version-sets/{name}" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The upsert replaces or creates the whole named version set. Fields you leave out of `version_set` return to their defaults: `agent_version_number` and `context_graph_version_number` to the latest versions, and `llm_model_preferences` to empty. Only `dynamic_behavior_sets` keeps what is stored when you leave it out or send `null`, and `[]` clears every pin. To change pins only, read the service, send its version set back with the pins changed, and pass the service's `updated_at` as `expected_updated_at`. A pin is replaced whole as well: a pin you send without `states` applies in every state, and one you send without `enabled` is enabled.

Creating a service and updating one accept pins in the same shape, and creating a service with pins needs `Service.update` as well as `Service.create`. An update that sends `version_sets` replaces the whole map: a version set you do not send is removed with its pins, and `release` must be present. The upsert changes one version set and leaves the others alone. Service reads return each version set with its `dynamic_behavior_sets`.

### Example

Read the service first. Its `version_sets.release` entry is what you send back, and its `updated_at` is the value for `expected_updated_at`. [Services](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md) covers the read. Here the entry pins no behaviors:

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/services/{service_id}" \
  -H "Authorization: Bearer <api-key>"
```

```json
{
  "agent_version_number": 3,
  "context_graph_version_number": 5,
  "llm_model_preferences": {},
  "dynamic_behavior_sets": []
}
```

The request below sends that entry back with one pin added. Copy `agent_version_number`, `context_graph_version_number`, and `llm_model_preferences` from your own read: a version number left out follows the latest version, and `llm_model_preferences` left out is emptied.

```bash
curl -X PUT "https://platform.api-us.concurrence.com/v1/{workspace_id}/services/{service_id}/version-sets/release" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "version_set": {
      "agent_version_number": 3,
      "context_graph_version_number": 5,
      "llm_model_preferences": {},
      "dynamic_behavior_sets": [
        {
          "set_id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
          "version": 2,
          "enabled": true,
          "states": ["billing_help"]
        }
      ]
    },
    "expected_updated_at": "2026-10-26T11:58:42.318204Z"
  }'
```

The response is `204` with no body. Read the service afterward: its `version_sets.release` entry shows the pins it runs.

```json
{
  "agent_version_number": 3,
  "context_graph_version_number": 5,
  "llm_model_preferences": {},
  "dynamic_behavior_sets": [
    {
      "set_id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
      "version": 2,
      "enabled": true,
      "states": ["billing_help"]
    }
  ]
}
```

### Move, Disable, or Clear a Pin <a href="#move-disable-or-clear-a-pin" id="move-disable-or-clear-a-pin"></a>

* **Move** a pin by upserting the version set with the same `set_id` and a different `version`. Send the whole pin, with the `enabled` and `states` you want it to keep. The version must exist, or the request returns `404`.
* **Disable** a pin with `"enabled": false`. It stays on the version set, still counts toward the 254-pin limit, and still blocks archiving the set. It does not count toward the 160,000-character budget. A service whose pins are all disabled runs as if it pinned nothing. A disabled pin applies to calls and conversations that load the service's configuration afterward, and a call that has already started can keep the configuration it loaded.
* **Clear** one pin by leaving it out of the list, or every pin with `"dynamic_behavior_sets": []`.

A write does not return the service's `updated_at`, so read the service again before the next one.

### Saving a Pin Applies It <a href="#saving-a-pin-applies-it" id="saving-a-pin-applies-it"></a>

A pin on `release` applies to calls and conversations that load the service's configuration after the save. A call that has already started can keep the configuration it loaded. See [Applying Version-Set Changes](https://docs.concurrence.com/platform-overview/deployment-model#applying-version-set-changes). A text conversation resumes with the behavior in force and the turns it has held. When its pin moved to another version in between, the hold carries over to the version the pin names, and earlier replies keep the version they ran with. A behavior that has been unpinned or disabled is not restored. A pin on another version set changes nothing that `release` runs.

### Checks on a Pin <a href="#checks-on-a-pin" id="checks-on-a-pin"></a>

Every write that stores pins checks them, and a failed check stores nothing:

* The set and version must exist in the workspace (`404`), and the set must not be archived (`409`).
* A version set holds at most 254 pins, one per set (`422`).
* The enabled pins' conditions and examples together carry at most 160,000 characters (`422`). Disabled pins, set names, and instructions do not count.
* Every name in `states` must be an action or data collection state of the Context Graph version the version set runs: its `context_graph_version_number`, or the graph's latest version when that is `null`. A decision state, an annotation state, an unknown name, or a name listed twice returns `422`. An empty `states` list reads no graph.

A pin check that finds problems returns `422` with each one named by its position in the list, its set id, and the field. The size budget is about the whole version set, so its entry has `null` for `index`, `id`, and `field`. This body has one of each:

```json
{
  "detail": {
    "message": "2 dynamic behavior pins are invalid in version set 'release'",
    "version_set": "release",
    "dynamic_behavior_sets": [
      {
        "index": 1,
        "id": "9d41c7e2-5a3b-4f08-b6d1-7c2e8a90f3b4",
        "field": "states",
        "message": "'follow_up' isn't an action or data collection state in this version"
      },
      {
        "index": null,
        "id": null,
        "field": null,
        "message": "enabled behaviors carry 160,412 characters of conditions and examples; the most is 160,000"
      }
    ]
  }
}
```

### Concurrent Edits <a href="#concurrent-edits" id="concurrent-edits"></a>

`expected_updated_at` is the service's `updated_at` exactly as the service returned it, with a time zone. When the service has changed since, the write returns `409` and stores nothing: reload the service and apply the change again. Without `expected_updated_at`, the write still lands only on the service as the request read it, so another writer's change in between is a `409` too. A value without a time zone returns `422`.

## Speech-to-Speech Voice Families <a href="#services-on-gpt-realtime" id="services-on-gpt-realtime"></a>

Dynamic behaviors run on text channels and on three voice families: the `concurrence` cascade (platform-managed voice), `gpt_realtime`, and `gpt_live` (GPT-Live). A `gpt_realtime` service can pin enabled behaviors, and runs them on single-state and multi-state graphs. Behaviors are offered, held, and ended by the same rules as on other channels. The agent starts its reply as the caller stops speaking, before that turn's choice is made, so a behavior chosen on a caller turn takes effect from a later reply, usually the reply to the caller's next turn. When you test a behavior on `gpt_realtime`, keep each test call going for at least one caller turn after the turn that should apply it.

Dynamic behaviors do not run on `eleven_realtime`, `grok_voice`, or `phonic` voice sessions: no choice is made and no instruction reaches the session. A write that would run a voice service's version set on one of these families while that version set pins an enabled behavior returns `422` and stores nothing:

```
eleven_realtime runs no dynamic behaviors, but version set 'release' pins 2 enabled dynamic behaviors. Disable or unpin the behaviors, or set voice_config.session_provider to 'concurrence'.
```

This applies to creating or updating a service and to the version set upsert, after the other pin checks pass. Only enabled pins count, so a version set whose pins are all disabled is accepted. A text service is not checked. See [Session Provider](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#session-provider).

## Context Graph Versions <a href="#context-graph-versions" id="context-graph-versions"></a>

A Context Graph version carries no dynamic behaviors. Its `dynamic_behaviors` field is deprecated: reads return an empty list, a create request accepts only `[]` or no field, and the runtime ignores the field. Create behaviors in the library and pin them.

Two checks tie pins to the graph:

* Changing a service's `context_graph_id` checks the stored pins' states against the graph it moves to and returns `422` when a pinned state is missing there.
* Creating a Context Graph version returns `422` when the version has no action or data collection state that a pin names, for each version set that follows the graph's latest version. The detail lists each service, version set, set, and missing states. A version set pinned to a specific graph version is not checked. Keep those states, or change the pins first.

## Read What Applied <a href="#read-what-applied" id="read-what-applied"></a>

On a conversation read, each agent message carries `dynamic_behavior`, the behavior its reply was rendered with: the set's `id`, `version`, `name`, and `mode`. It is `null` when no behavior was in force for the reply, on user and system messages, and on an agent line the agent did not generate from the conversation, such as a filler, an emergency script, a correction, or an operator's words, even while a behavior is in force. It is on `GET /v1/{workspace_id}/conversations/{conversation_id}`, on its `/turns` list, and on the agent message of a `POST` turn response.

```json
{
  "role": "agent",
  "text": "I can help with that bill. Which visit does it cover?",
  "dynamic_behavior": {
    "id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
    "version": 2,
    "name": "Billing questions",
    "mode": "add"
  }
}
```

A call's detail lists turns. Each turn carries `dynamic_behavior` and `dynamic_behavior_decision`, which records what the caller turn's choice did, or `null` when no choice ran. The call also lists `triggered_behaviors`, the names of the behaviors its agent lines ran with, in order of first use. It is the [compatibility call detail](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#compatibility-call-detail), `GET /v1/{workspace_id}/calls/{call_id}`.

Read `dynamic_behavior_decision` on the day of the call. About a day after a call, its turns are rebuilt from the saved transcript, which keeps each reply's `dynamic_behavior` and the call's `triggered_behaviors` and leaves `dynamic_behavior_decision` `null` on every turn. A text conversation read returns the behavior each reply used, and the choice made on each caller turn is returned on calls.

```json
{
  "dynamic_behavior": {
    "id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
    "version": 2,
    "name": "Billing questions",
    "mode": "add"
  },
  "dynamic_behavior_decision": {
    "outcome": "applied",
    "behavior_id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
    "behavior_version": 2,
    "chosen_id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
    "chosen_version": 2,
    "confidence": 0.82,
    "candidate_count": 6,
    "context_graph_version": 3,
    "cited_message_indexes": [0]
  }
}
```

A skipped turn records why:

```json
{
  "outcome": "skipped",
  "reason": "person_request",
  "context_graph_version": 3,
  "cited_message_indexes": [2, 3]
}
```

On a call, a choice that lands after a reply was rendered is recorded on the turn as `dynamic_behavior_decision`, and the reply that was already spoken keeps the `dynamic_behavior` it ran with. A decision record has `behavior_id` and `behavior_version` for the behavior in force after the choice, `chosen_id` and `chosen_version` for what the selector chose, `confidence` (`null` when none is reported, and a choice with no confidence counts as having enough, so `below_floor` does not apply to it), `candidate_count` for the behaviors offered, and `cited_message_indexes` for the turn's own messages, the agent's line before it and then the caller's (the selector reads earlier turns too). While a call is live, its observer connection delivers a `dynamic_behavior_decided` event when a caller turn's choice lands. See [Observer Events](https://docs.concurrence.com/developer-guide/platform-api/conversations/observer-events.md#state-and-navigation).

| `outcome`                       | Meaning                                                                                                                                                                                                                                               |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applied`                       | The chosen behavior is in force.                                                                                                                                                                                                                      |
| `kept`                          | The behavior in force stays because the selector chose it again or said, with enough confidence, that it still applies.                                                                                                                               |
| `held`                          | The behavior in force stays because it is inside its `sticky_turns` and the selector chose none, chose another behavior without enough confidence, or gave no usable answer. A different behavior chosen with enough confidence is `applied` instead. |
| `none`, `below_floor`, `failed` | Nothing is in force after the decision: no behavior applies, a choice without enough confidence, or no usable answer.                                                                                                                                 |
| `skipped`                       | No choice ran and the behavior in force ended. `reason` says why.                                                                                                                                                                                     |
| `superseded`                    | The caller's next turn cancelled the choice before it landed. The behavior in force stays as it was.                                                                                                                                                  |

On a skip, `reason` is `emergency_floor` (the platform recognized a medical emergency or self-harm), `person_request` (the caller asked for a person), `empathy_hold` (the turn was at the highest empathy tier), `no_candidates` (no enabled pin applies in the current state), or `suspended` (the platform has paused dynamic behaviors for the service or its workspace). Recognizing an emergency or a request for a person is a pattern check on the caller's words in English and Spanish. It covers a limited set of phrasings and can miss others, and the choice runs on a turn it misses. See [How Long a Behavior Stays](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors#how-long-a-behavior-stays).

On a `failed` outcome, and on a `held` one that came from a failed choice, `reason` says why the selector gave no usable answer:

* `refusal`, `out_of_set`, and `malformed`: it answered, but the answer could not be used. It declined, chose something that was not offered, or gave an answer that could not be read.
* `http_4xx`, `http_retryable`, `connection`, and `timeout`: the request was rejected, hit a retryable error, lost its connection, or ran out of time.
* `breaker_open`: the platform had paused sending requests after repeated failures.
* `options_exceeded`: a request offered more behaviors than the selector accepts.

The next caller turn runs its own choice.

| What you see                        | What to check                                                                                                                                                                                      |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` on a turn that should match  | Sharpen the condition and add examples in the callers' words. See [Author Dynamic Behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/authoring-dynamic-behaviors.md). |
| `below_floor`                       | The selector chose a behavior without enough confidence. Sharpen its condition and separate it from its neighbors.                                                                                 |
| `skipped` with `no_candidates`      | No enabled pin applies in the state the turn started in. Check the pin's `enabled` and `states`.                                                                                                   |
| `failed`, or `held` with a `reason` | The selector gave no usable answer for that turn. If it repeats, contact your Concurrence representative with the call id.                                                                         |
| `skipped` with `suspended`          | The platform has paused dynamic behaviors for the service or its workspace.                                                                                                                        |

## Retire a Set <a href="#retire-a-set" id="retire-a-set"></a>

A set cannot be deleted. To retire one, [see which services pin it](#see-which-services-pin-a-set), [clear its pin](#move-disable-or-clear-a-pin) from every version set that holds it (a disabled pin counts too), and then [archive it](#archive-and-restore-a-set). Archiving takes the set out of the default list and frees its name, and restoring it brings it back.

## See Which Services Pin a Set <a href="#see-which-services-pin-a-set" id="see-which-services-pin-a-set"></a>

The usage operation lists the services whose version sets pin a set. Each item is a service, with its `id` and its own `name`, and the version sets that pin the set, each with the pinned `version`, `enabled`, and `states`. Disabled pins are listed. Items come in service-name order and page with `limit`, 50 by default and up to 200. A set that nothing pins returns an empty list. To list the sets one service pins, use the set list with `service_id`.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets/{set\_id}/usage" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}/usage" \
  -H "Authorization: Bearer <api-key>"
```

### Example Response

```json
{
  "items": [
    {
      "id": "e47a09b3-52c8-4d1f-a6e0-93b7d1c25f84",
      "name": "Front Desk Line",
      "version_sets": [
        {
          "name": "release",
          "version": 2,
          "enabled": true,
          "states": ["billing_help"]
        }
      ]
    }
  ],
  "has_more": false,
  "continuation_token": null
}
```

## Archive and Restore a Set <a href="#archive-and-restore-a-set" id="archive-and-restore-a-set"></a>

Update a set to rename it, change its tags, or archive it. A field you leave out stays as it is, and the update writes no version. A set cannot be deleted. Archiving takes it out of the default list and frees its name. Restoring it with `archived: false` brings it back, and returns `409` when another set that is not archived has taken the name.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets/{set\_id}" method="patch" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

A set that any version set pins, enabled or not, cannot be archived: the request returns `409`, stores nothing, and names up to ten services with their version sets. [Clear its pins](#move-disable-or-clear-a-pin) first. Sending the current name or tags, archiving an archived set, or sending `{}` returns `200` and changes and audits nothing.

A set's name belongs to the set, not to a version. Renaming a pinned set changes the name the selector reads, and the name recorded on later replies, for every service that pins it. It involves no version write and no pin change.

### Example

```bash
curl -X PATCH "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}'
```

To restore the set, send `{"archived": false}`.

## List and Get Sets <a href="#list-and-get-sets" id="list-and-get-sets"></a>

A list returns the workspace's sets without their versions, newest update first. By default it returns only sets that are not archived.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

Narrow the list with these query parameters:

* `q`: the name contains this text, in any case. `%` and `_` match themselves.
* `tag`: sets that carry this exact tag.
* `archived`: `true` lists only archived sets.
* `service_id`: sets that any version set of this service pins, enabled or not. The list is empty when the service is not in the workspace.
* `sort_by`: `+name`, `-name`, `+updated_at`, or `-updated_at`. Repeat it for more keys, applied left to right. In a URL, write the plus sign as `%2B`.

A change to a set's name, tags, or archive state, or a version write, moves the set to the front of the default list. When `has_more` is `true`, send the returned `continuation_token` back unchanged to get the next page. See [Pagination](https://docs.concurrence.com/developer-guide/platform-api/platform-api/pagination.md).

### Example

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets?tag=billing&sort_by=%2Bname&limit=20" \
  -H "Authorization: Bearer <api-key>"
```

### Example Response

```json
{
  "items": [
    {
      "id": "3f2b8c1e-9d4a-4e6b-8a1c-5d7e9f0a1b2c",
      "workspace_id": "c8e1f2a4-6b7d-4f3e-9a10-2b5d8c7e4f61",
      "name": "Billing questions",
      "tags": ["billing"],
      "latest_version": 2,
      "archived_at": null,
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-10-26T14:05:11.482913Z",
      "updated_at": "2026-10-26T14:22:40.108377Z"
    }
  ],
  "has_more": false,
  "continuation_token": null
}
```

Get a set by its id. An archived set is returned too. A set of another workspace, or an id the workspace does not have, returns `404`.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets/{set\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}" \
  -H "Authorization: Bearer <api-key>"
```

## List and Get Versions <a href="#list-and-get-versions" id="list-and-get-versions"></a>

A set's versions come newest first, 20 per page by default and up to 100, and page like the set list.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets/{set\_id}/versions" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}/versions?limit=5" \
  -H "Authorization: Bearer <api-key>"
```

A version is returned as it was written, with its `condition`, `examples`, `instruction`, `mode`, `sticky_turns`, and `note`. A version the set does not have returns `404`.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/dynamic-behavior-sets/{set\_id}/versions/{version}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

```bash
curl "https://platform.api-us.concurrence.com/v1/{workspace_id}/dynamic-behavior-sets/{set_id}/versions/2" \
  -H "Authorization: Bearer <api-key>"
```

## Permissions <a href="#permissions" id="permissions"></a>

Requests use the same Bearer API key as every other Platform route. The role behind the key decides what it can do:

| Operation                                       | Permission                                                  |
| ----------------------------------------------- | ----------------------------------------------------------- |
| List and get sets, list and get versions, usage | `DynamicBehaviorSet.view`                                   |
| Create a set                                    | `DynamicBehaviorSet.create`                                 |
| Rename, retag, or write a version               | `DynamicBehaviorSet.update`                                 |
| Archive a set                                   | `DynamicBehaviorSet.update` and `DynamicBehaviorSet.delete` |
| Pin, move, or clear a pin                       | `Service.update`                                            |
| Read a service and its pins                     | `Service.view`                                              |

Every role holds `DynamicBehaviorSet.view` and `Service.view`. Only `admin` and `owner` hold the create, update, and delete permissions, so a `viewer`, `operator`, or `member` key gets `403` on every write. A role that can read a version can read its instruction, so write instructions as text any member of the workspace can read.

Replace mode needs the same permissions as `add` mode. An `admin` or `owner` key creates a set whose first version is in `replace` mode, writes a later `replace` version, restores one as a new version, and pins, moves, enables, disables, or removes a pin on one.

Setting a set's own `id` when you create it needs the `platform:admin` scope on top of the role. No workspace role includes the scope, `owner` and `admin` included. A workspace cannot delegate it, and a workspace API key does not carry it, so leave `id` out and let the platform generate it. The scope does not replace the role: a `viewer` that holds it still gets `403`.

Library changes and changes to a version set's pins are written to the audit log on a best-effort basis after the change commits. A failed audit write does not block or undo the change, so monitor audit delivery. `admin` and `owner` can read the log. The events are: `dynamic_behavior_set.create`, `dynamic_behavior_set.update`, `dynamic_behavior_set.archive`, `dynamic_behavior_set.unarchive`, `dynamic_behavior_set.version.create`, and `service.dynamic_behavior_sets.update`. A refused or unchanged write sends no event. Events carry ids, names, tags, versions, modes, and counts, not the text of a condition, example, or instruction. See [Compliance and Audit](https://docs.concurrence.com/operations-and-safety/compliance).

## Limits <a href="#limits" id="limits"></a>

Whitespace around every text field is trimmed before its length is checked.

Each operation's reference gives the bounds of its fields. These are the limits to plan around:

| Item                 | Limit                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| Set name             | 1 to 120 characters. Unique among the workspace's sets that are not archived, ignoring case.         |
| `condition`          | Required, 1 to 1,000 characters.                                                                     |
| `examples`           | At most 50, each 1 to 500 characters.                                                                |
| `instruction`        | `null`, or 1 to 50,000 characters. Required when `mode` is `replace`.                                |
| `sticky_turns`       | 1 to 5. The default is 1.                                                                            |
| Pins per version set | At most 254, one per set, enabled or not.                                                            |
| Selection budget     | The enabled pins' conditions and examples together carry at most 160,000 characters per version set. |

On each caller turn the selector reads the conditions and examples of the behaviors offered on that turn, so fewer offered behaviors give it less to read. A caller turn that runs a choice makes one more model call, which is counted in usage like other model usage and, on text, adds its time to the reply. Library writes and the version set upsert use the common write policy, 10 requests per minute, and library reads use the common read policy, 60 per minute, each per credential and route. A request over the limit returns `429` with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. See [Rate Limits](https://docs.concurrence.com/reference/performance#api-rate-limits).

## Errors <a href="#errors" id="errors"></a>

### Library Operations

| Status         | Cause                                                                                                                                                                                            | What to do                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `401`          | The credential is missing or invalid.                                                                                                                                                            | Send a valid workspace API key as a Bearer token.                                                     |
| `403`          | `Missing permission: DynamicBehaviorSet:Create`, or the same for `View`, `Update`, or `Delete`.                                                                                                  | Use a key whose role holds the permission, `admin` or `owner` for writes.                             |
| `403` or `409` | `Setting a dynamic behavior set's id requires platform:admin scope`, or `A dynamic behavior set with id <id> already exists, or the name 'X' is in use`                                          | Leave `id` out of the request. Setting it needs `platform:admin`.                                     |
| `404`          | `Dynamic behavior set not found: <id>`                                                                                                                                                           | Check the id and the workspace. A set of another workspace is not found.                              |
| `404`          | `Dynamic behavior set version not found: <set_id>/v<version>`                                                                                                                                    | List the set's versions and use one that exists.                                                      |
| `405`          | `PUT`, `PATCH`, or `DELETE` on a version.                                                                                                                                                        | A version cannot be edited or deleted. Write the next version.                                        |
| `409`          | `A dynamic behavior set named 'X' already exists in this workspace`, on create, rename, or restore.                                                                                              | Use another name, or rename or archive the set that holds it.                                         |
| `409`          | `Dynamic behavior set is at version N; this write expected M. Reload and apply the change to version N.`                                                                                         | Read the set, apply your change to version N, and send again with `expected_latest_version` set to N. |
| `409`          | `Dynamic behavior set is archived; restore it before adding a version`                                                                                                                           | Restore the set with `archived: false`, then write the version.                                       |
| `409`          | `Cannot archive a dynamic behavior set that version sets pin. Unpin it from: ...`                                                                                                                | Move the listed pins off the set or remove them, then archive.                                        |
| `422`          | A body outside its bounds, an unknown field, `replace` without an instruction, a missing or out-of-range `expected_latest_version`, a `set_id` that is not a UUID, or an invalid list parameter. | Fix the field the `detail` names. See [Limits](#limits).                                              |
| `429`          | Rate limit exceeded.                                                                                                                                                                             | Wait the number of seconds in `Retry-After`.                                                          |

### Pins and Services

| Status | Cause                                                                                                                                                                     | What to do                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | `Missing permission: Service:Update`                                                                                                                                      | Pin with an `admin` or `owner` key.                                                                                                                        |
| `404`  | `Dynamic behavior set <set_id> version <n> not found (version set 'release')`                                                                                             | List the set's versions and pin one that exists in this workspace.                                                                                         |
| `409`  | `Archived dynamic behavior sets can't be pinned (version set 'release'): 'name'. Unarchive them or unpin them.`                                                           | Restore the set, or leave it out of the pins.                                                                                                              |
| `409`  | `The service changed since it was read, so nothing was stored. Reload it and apply the change again.`                                                                     | Read the service, apply your change to what it returns, and send again.                                                                                    |
| `422`  | A pin check body, as in [Checks on a Pin](#checks-on-a-pin): a state that is not an action or data collection state, a name listed twice, or a size over the budget.      | Fix the entries the body names.                                                                                                                            |
| `422`  | A set pinned twice, more than 254 pins, or an `expected_updated_at` without a time zone.                                                                                  | Fix the request. See [Limits](#limits).                                                                                                                    |
| `422`  | `<family> runs no dynamic behaviors, but version set 'release' pins ...`, where `<family>` is `eleven_realtime`, `grok_voice`, or `phonic`                                | Disable or unpin the behaviors, or set `voice_config.session_provider` to `concurrence`. See [Speech-to-Speech Voice Families](#services-on-gpt-realtime). |
| `422`  | Creating a Context Graph version: `This version of context graph 'X' has no state that some dynamic behavior pins apply in. Keep those states, or change the pins first.` | Keep the states the detail lists, or change those pins first.                                                                                              |
| `422`  | A Context Graph version with a `dynamic_behaviors` list that is not empty.                                                                                                | Send `[]` or leave the field out. Create the behaviors in the library and pin them.                                                                        |

## Related Pages

* [Author Dynamic Behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/authoring-dynamic-behaviors.md) covers writing, testing, and rolling back behaviors.
* [Services](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md) covers version sets and the `gpt_realtime` session provider.
* [Voice Agent](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#compatibility-call-detail) covers the call detail that returns each caller turn's choice, and [Conversations](https://docs.concurrence.com/developer-guide/platform-api/conversations.md) the conversation reads that return the behavior a reply used.
* [Observer Events](https://docs.concurrence.com/developer-guide/platform-api/conversations/observer-events.md) lists the event a live call delivers when a choice lands.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
