Dynamic Behaviors

Create trigger-based behavior sets that inject instructions or modify tool availability during conversations.

Manage organization-scoped, versioned sets of trigger-based behaviors that activate during conversations. This page documents the core API endpoints for creating, updating, and managing Dynamic Behavior Sets and their versions.

API Terminology In the API, these are called "Dynamic Behavior Sets" (dynamic_behavior_set). In our conceptual documentation and platform UI, we refer to them as "Dynamic Behaviors" - configurable rules that inject instructions or modify tool availability based on conversation context. See Conceptual Docs: Dynamic Behaviors for the architectural perspective.

Overview

Dynamic Behavior Sets are versioned collections of trigger-action rules that activate during conversations when specific patterns are detected. Each set contains:

Conversation Triggers: Natural-language descriptions of conversation patterns that activate the behavior (matched via semantic similarity).
Actions: Operations performed when a trigger fires. Two action types are supported:
- inject-instruction: Injects additional instructions into the agent's context.
- change-tool-candidates: Modifies the set of tools available to the agent.

Key Properties

Organization-scoped: Each behavior set belongs to a single organization.
Versioned: Each set maintains a version history. New versions are created with incremented version numbers.
Service-bound: Behavior sets are applied to one or more services and activated via version sets.
Activatable: Sets have an is_active flag that controls whether they are eligible for invocation.

How They Relate to Services

Dynamic Behavior Sets are applied to services through version sets. When a conversation is created with a specific version set, the platform evaluates the associated behavior sets' triggers against each user message. When a trigger matches, the corresponding actions execute within that interaction.

Service: "Health Coach"
├─ Version Set: "release"
│   └─ Behaviors: [
│       "Emergency Response Protocol",
│       "Calorie Target Guidance"
│     ]
└─ Version Set: "staging"
    └─ Behaviors: [
        "Emergency Response Protocol",
        "Calorie Target Guidance",
        "Medication Side Effects Guide"   // Testing new behavior
      ]

For more on configuring version sets, see Version Sets & Promotion. For data access and table schemas, see Dynamic Behaviors Data Access.

Typical Lifecycle

Create a behavior set with an initial version (name, triggers, actions).
Apply it to one or more services.
Test in a staging version set.
Activate the set (is_active: true) and promote to release.
Create new versions as triggers or actions evolve.
Query invocation history to verify trigger accuracy.

Action Types

Inject Instruction

Adds or overrides the agent's instructions when a trigger fires.

{
  "type": "inject-instruction",
  "instruction": "If the user mentions chest pain, immediately recommend calling emergency services.",
  "overrides_instructions": false
}

Field

Type

Description

type

string

Must be "inject-instruction"

instruction

string

The instruction text to inject

overrides_instructions

boolean

If true, replaces the state's original instruction. If false, appends to it.

Change Tool Candidates

Modifies the tools available to the agent when a trigger fires.

{
  "type": "change-tool-candidates",
  "tool_call_specs": [
    {
      "tool_id": "670a1234567890abcdef1234",
      "version_constraint": ">=1.0.0",
      "additional_instruction": "Use this tool to look up drug interactions",
      "result_persistence": "persisted-preferred"
    }
  ],
  "overrides_existing_tool_call_specs": false
}

Field

Type

Description

type

string

Must be "change-tool-candidates"

tool_call_specs

array

List of tool call specifications to add or replace

overrides_existing_tool_call_specs

boolean

If true, replaces existing tool specs. If false, adds to them.

Create a Dynamic Behavior Set

Create a new dynamic behavior set along with its initial version. The initial version defines the triggers and actions that will be active when the set is activated.

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/dynamic_behavior_set/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "name": "Emergency Response Protocol",
  "tags": {"category": "safety", "priority": "high"},
  "applied_to_services": ["6618791275130b73714e8d1c"],
  "initial_version": {
    "is_active": true,
    "conversation_triggers": [
      "The user mentions feeling suicidal or self-harm",
      "The user describes a medical emergency"
    ],
    "actions": [
      {
        "type": "inject-instruction",
        "instruction": "Immediately provide emergency hotline numbers and recommend the user call 911.",
        "overrides_instructions": true
      }
    ]
  }
}'

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    result = client.dynamic_behavior_set.create(
        name="Emergency Response Protocol",
        tags={"category": "safety", "priority": "high"},
        applied_to_services=["6618791275130b73714e8d1c"],
        initial_version={
            "is_active": True,
            "conversation_triggers": [
                "The user mentions feeling suicidal or self-harm",
                "The user describes a medical emergency",
            ],
            "actions": [
                {
                    "type": "inject-instruction",
                    "instruction": "Immediately provide emergency hotline numbers and recommend the user call 911.",
                    "overrides_instructions": True,
                }
            ],
        },
    )
    print(f"Created: {result.dynamic_behavior_set_id}")

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
const result = await client.dynamicBehaviorSet.create({
  name: "Emergency Response Protocol",
  tags: { category: "safety", priority: "high" },
  applied_to_services: ["6618791275130b73714e8d1c"],
  initial_version: {
    is_active: true,
    conversation_triggers: [
      "The user mentions feeling suicidal or self-harm",
      "The user describes a medical emergency",
    ],
    actions: [
      {
        type: "inject-instruction",
        instruction:
          "Immediately provide emergency hotline numbers and recommend the user call 911.",
        overrides_instructions: true,
      },
    ],
  },
});
console.log(`Created: ${result.dynamic_behavior_set_id}`);

Response (201):

{
  "dynamic_behavior_set_id": "6618791275130b73714e8d1c"
}

Rate Limit: 200 requests per minute.

Create a dynamic behavior set

post

/v1/{organization}/dynamic_behavior_set/

Create a new dynamic behavior set as well as its initial version.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:CreateDynamicBehaviorInstruction on the set to create.
DynamicBehaviorInstruction:UpdateDynamicBehaviorInstruction on the set to create.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

namestring · min: 1Required

The name of the dynamic behavior set.

applied_to_servicesstring[]Required

The services that the dynamic behavior set should be applied to.

Responses

201

Succeeded.

application/json

dynamic_behavior_set_idstringRequired

The ID of the newly created dynamic behavior set.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization, service, or tool does not exist.

409

If the initial version is defined and is_active is set to True, an active dynamic behavior set with the same name already exists.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 200 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/dynamic_behavior_set/

POST /v1/{organization}/dynamic_behavior_set/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "name": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "applied_to_services": [
    "text"
  ],
  "initial_version": {
    "is_active": true,
    "conversation_triggers": [
      "text"
    ],
    "actions": [
      {
        "type": "text",
        "instruction": "text",
        "overrides_instructions": true
      }
    ]
  }
}

{
  "dynamic_behavior_set_id": "text"
}

List Dynamic Behavior Sets

Retrieve dynamic behavior sets matching the given filters. Only sets the authenticated user has DynamicBehaviorInstruction:GetDynamicBehaviorInstruction permission for are returned.

Common filters:

id=<id> (repeatable) - filter by specific IDs
is_active=true|false - filter by active status
applied_to_service=<service_id> (repeatable) - filter by associated service
creator=<org_id,user_id> (repeatable) - filter by creator
tag=key:value (repeatable; value may be * for any value or empty for null)
sort_by=+updated_at|-updated_at (repeatable)
limit (0-50, default 50), continuation_token (int, default 0)

curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/dynamic_behavior_set/?limit=10&is_active=true' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    result = client.dynamic_behavior_set.list(limit=10, is_active=True)
    for dbs in result.dynamic_behavior_sets:
        print(f"{dbs.name} (ID: {dbs.id}, active: {dbs.is_active})")

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
const result = await client.dynamicBehaviorSet.list({
  limit: 10,
  is_active: true,
});
result.dynamic_behavior_sets?.forEach((dbs) => {
  console.log(`${dbs.name} (ID: ${dbs.id}, active: ${dbs.is_active})`);
});

Rate Limit: 500 requests per minute.

Get dynamic behavior sets

get

/v1/{organization}/dynamic_behavior_set/

Retrieve dynamic behavior sets that match the given filters.

Permissions

This endpoint may be impacted by the following permissions:

Only dynamic behavior sets that the authenticated user has DynamicBehaviorInstruction:GetDynamicBehaviorInstruction permission for will be retrieved.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Query parameters

idstring[]Optional

The IDs of the dynamic behavior sets to retrieve.

Default: []

limitinteger · max: 50Optional

The maximum number of dynamic behavior sets to return.

Default: 50

continuation_tokenintegerOptional

The continuation token to use to retrieve the next set of dynamic behavior sets.

Default: 0

is_activeany ofOptional

Whether the dynamic behavior set is active.

booleanOptional

nullOptional

applied_to_servicestring[]Optional

The IDs of the services that the dynamic behavior set is applied to.

Default: []

creatorstring[]Optional

The creators of the dynamic behavior sets.

Default: []

tagstring[]Optional

The tags of the dynamic behavior sets. Must be specified using the syntax key:value, which means to match all sets with the given key and value pair among its tags. If value is *, it means the value does not matter. If value is empty, it matches against when the value is None.

Default: []

sort_bystring[]Optional

The fields to sort the sets by. Supported fields are updated_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 500 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/dynamic_behavior_set/

GET /v1/{organization}/dynamic_behavior_set/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "dynamic_behavior_sets": [
    {
      "id": "text",
      "name": "text",
      "is_active": true,
      "applied_to_services": [
        "text"
      ],
      "tags": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "created_at": "2026-03-23T20:30:36.487Z",
      "creator": {
        "org_id": "text",
        "user_id": "text"
      },
      "updated_at": "2026-03-23T20:30:36.487Z",
      "updated_by": {
        "org_id": "text",
        "user_id": "text"
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "filter_values": {
    "applied_to_services_ids": [
      "text"
    ],
    "creators": [
      {
        "org_id": "text",
        "user_id": "text"
      }
    ],
    "tags": [
      "text"
    ]
  }
}

Search Dynamic Behavior Sets

Search for dynamic behavior sets by text query. The query matches against set names and the triggers of the latest version. Returns the top 50 results sorted by relevance.

Rate Limit: 50 requests per minute.

Search dynamic behavior sets

get

/v1/{organization}/dynamic_behavior_set/search

Search for dynamic behavior sets that match the given filters and contain the given query in its name and the triggers of its latest version. Only the top 50 results will be returned. The results will be sorted by the relevance of the search query.

Permissions

This endpoint may be impacted by the following permissions:

Only dynamic behavior sets that the authenticated user has DynamicBehaviorInstruction:GetDynamicBehaviorInstruction permission for will be retrieved.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Query parameters

querystring · min: 1Required

The query to search for. Any sets containing the terms in its name and the triggers of its latest version would be returned.

is_activeany ofOptional

Whether the dynamic behavior set is active.

booleanOptional

nullOptional

applied_to_servicestring[]Optional

The IDs of the services that the dynamic behavior set is applied to.

Default: []

creatorstring[]Optional

The creators of the dynamic behavior sets. Each value must be of the format org_id,user_id.

Default: []

tagstring[]Optional

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/dynamic_behavior_set/search

GET /v1/{organization}/dynamic_behavior_set/search?query=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "dynamic_behavior_sets": [
    {
      "id": "text",
      "name": "text",
      "is_active": true,
      "applied_to_services": [
        "text"
      ],
      "tags": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "created_at": "2026-03-23T20:30:36.487Z",
      "creator": {
        "org_id": "text",
        "user_id": "text"
      },
      "updated_at": "2026-03-23T20:30:36.487Z",
      "updated_by": {
        "org_id": "text",
        "user_id": "text"
      }
    }
  ]
}

Update a Dynamic Behavior Set

Update a dynamic behavior set's metadata, service associations, or active status. All fields are optional; only provided fields are updated.

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/dynamic_behavior_set/<BEHAVIOR-SET-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "is_active": false,
  "tags": {"category": "safety", "status": "deprecated"}
}'

If is_active is set to true, the update will fail with HTTP 409 if another active set with the same name already exists.

Rate Limit: 500 requests per minute.

Update a dynamic behavior set

post

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/

Update a dynamic behavior set.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:UpdateDynamicBehaviorInstruction on the dynamic behavior set to update.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set to delete.

Pattern: ^[a-f0-9]{24}$

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

nameany ofOptional

The name of the dynamic behavior set.

string · min: 1Optional

nullOptional

tagsany ofOptional

The tags of the dynamic behavior set. Both the key and the value can only contain alphanumeric characters, underscores, or spaces.

nullOptional

applied_to_servicesany ofOptional

The services that the dynamic behavior set should be applied to.

string[]Optional

nullOptional

is_activeany ofOptional

Whether the dynamic behavior set is active.

booleanOptional

nullOptional

Responses

204

Succeeded.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization, dynamic behavior set, or service does not exist.

409

Another active set with the same name already exists.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 500 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/

POST /v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 105

{
  "name": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "applied_to_services": [
    "text"
  ],
  "is_active": true
}

No content

Delete a Dynamic Behavior Set

Permanently delete a dynamic behavior set.

Deletion is permanent. Deactivate a set (is_active: false) instead if you may need it again.

Rate Limit: 500 requests per minute.

Delete a dynamic behavior instruction

delete

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/

Delete a dynamic behavior set.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:DeleteDynamicBehaviorInstruction on the dynamic behavior set to delete.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set to delete.

Pattern: ^[a-f0-9]{24}$

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization or dynamic behavior set does not exist.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 500 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

delete

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/

DELETE /v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

Get Invocations

Retrieve the invocation history for a dynamic behavior set - a record of when and where the behavior's triggers fired during conversations. Useful for verifying trigger accuracy and auditing activation frequency.

Common filters:

limit (1-30, default 30)
continuation_token (int, default 0)
sort_by=+invoked_at|-invoked_at (repeatable)

Only invocations from messages that the authenticated user has the Conversation:GetMessage permission for are returned.

Rate Limit: 50 requests per minute.

Get dynamic behavior invocations

get

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/invocation/

Retrieve the dynamic behavior invocations for a dynamic behavior set.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:GetDynamicBehaviorInstruction for the dynamic behavior set.

This endpoint is impacted by the following permissions:

Only invocations from messages that the authenticated user has the Conversation:GetMessage permission for are returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set.

Pattern: ^[a-f0-9]{24}$

Query parameters

limitinteger · max: 30Optional

The maximum number of dynamic behavior invocations to return.

Default: 30

continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of dynamic behavior invocations.

Default: 0

sort_bystring[]Optional

The fields to sort the versions by. Supported fields are invoked_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or dynamic behavior set is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/invocation/

GET /v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/invocation/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "dynamic_behavior_invocations": [
    {
      "_id": "text",
      "org_id": "text",
      "created_at": "2026-03-23T20:30:36.487Z",
      "updated_at": "2026-03-23T20:30:36.487Z",
      "conversation_id": "text",
      "service_id": "text",
      "user_id": "text",
      "initial_message_id": "text",
      "agent_message_id": "text",
      "agent_inner_thoughts_ids": [
        "text"
      ],
      "dynamic_behavior_set_version_info": [],
      "invoked_at": "2026-03-23T20:30:36.487Z",
      "external_event_message_ids": [
        "text"
      ]
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Create a Version

Create a new version of an existing dynamic behavior set. Each version defines a complete set of triggers and actions. Version numbers are automatically incremented.

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/dynamic_behavior_set/<BEHAVIOR-SET-ID>/version/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "conversation_triggers": [
    "The user mentions feeling suicidal or self-harm",
    "The user describes a medical emergency",
    "The user mentions harming others"
  ],
  "actions": [
    {
      "type": "inject-instruction",
      "instruction": "Immediately provide crisis resources: 988 Suicide & Crisis Lifeline, 911 for emergencies.",
      "overrides_instructions": true
    }
  ]
}'

Response (201):

{
  "new_version_number": 3
}

You can optionally pass ?version=<n> as a query parameter to assert the expected version number. If the next version does not match, the request returns HTTP 400.

Rate Limit: 200 requests per minute.

Create a new version of a dynamic behavior set.

post

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/

Create a new version of the given dynamic behavior set.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:UpdateDynamicBehaviorInstruction on the dynamic behavior set to create a new version for.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set to delete.

Pattern: ^[a-f0-9]{24}$

Query parameters

versionany ofOptional

The version number of the new version. If specified, this endpoint throws an error if the next version in the database doesn't equal to the value of this parameter.

integerOptional

nullOptional

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

conversation_triggersstring[] · min: 1 · max: 50Required

The conversation triggers for the dynamic behavior set version.

Responses

201

Succeeded.

application/json

new_version_numberintegerRequired

The version number of the new version.

400

The specified version number is not the expected next version to be created.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization, dynamic behavior set, or tool does not exist.

422

Invalid request path parameter, request query parameter, or request body failed validation.

429

The user has exceeded the rate limit of 200 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/

POST /v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 113

{
  "conversation_triggers": [
    "text"
  ],
  "actions": [
    {
      "type": "text",
      "instruction": "text",
      "overrides_instructions": true
    }
  ]
}

{
  "new_version_number": 1
}

Get Versions

Retrieve the version history for a dynamic behavior set.

Common filters:

version=<constraint> - exact version number, or "latest" for the most recent
limit (1-10, default 10)
continuation_token (int, default 0)
sort_by=+version|-version (repeatable)

Rate Limit: 1000 requests per minute.

Get dynamic behavior set versions

get

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/

Get the versions of a dynamic behavior set.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:GetDynamicBehaviorInstruction for the dynamic behavior set to retrieve.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set.

Pattern: ^[a-f0-9]{24}$

Query parameters

versionany ofOptional

The versions of the dynamic behavior set to retrieve. One can specify an exact version to retrieve, which is either the version number or latest, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -, and every version within the range would be retrieved.

Example: 1

stringOptional

nullOptional

limitinteger · max: 10Optional

The maximum number of dynamic behavior set versions to return.

Default: 10

continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of dynamic behavior set versions.

Default: 0

sort_bystring[]Optional

The fields to sort the versions by. Supported fields are version. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or dynamic behavior set is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 1000 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/

GET /v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "dynamic_behavior_set_versions": [
    {
      "_id": "text",
      "org_id": "text",
      "created_at": "2026-03-23T20:30:36.487Z",
      "updated_at": "2026-03-23T20:30:36.487Z",
      "dynamic_behavior_set_id": "text",
      "version": 1,
      "conversation_triggers": [
        "text"
      ],
      "actions": [
        {
          "type": "text",
          "instruction": "text",
          "overrides_instructions": true
        }
      ],
      "creator": {
        "org_id": "text",
        "user_id": "text"
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Core API -> Services (version sets and behavior application)
Best Practices -> Version Sets & Promotion
Data Access -> Dynamic Behaviors Tables
Getting Started -> Authentication

PreviousTools NextMetrics

Last updated 1 day ago

Was this helpful?

Good evening

hashtagOverview

hashtagKey Properties

hashtagHow They Relate to Services

hashtagTypical Lifecycle

hashtagAction Types

hashtagInject Instruction

hashtagChange Tool Candidates

hashtagCreate a Dynamic Behavior Set

hashtagCreate a dynamic behavior set

Permissions

hashtagList Dynamic Behavior Sets

hashtagGet dynamic behavior sets

Permissions

hashtagSearch Dynamic Behavior Sets

hashtagSearch dynamic behavior sets

Permissions

hashtagUpdate a Dynamic Behavior Set

hashtagUpdate a dynamic behavior set

Permissions

hashtagDelete a Dynamic Behavior Set

hashtagDelete a dynamic behavior instruction

Permissions

hashtagGet Invocations

hashtagGet dynamic behavior invocations

Permissions

hashtagCreate a Version

hashtagCreate a new version of a dynamic behavior set.

Permissions

hashtagGet Versions

hashtagGet dynamic behavior set versions

Permissions

hashtagRelated

Overview

Key Properties

How They Relate to Services

Typical Lifecycle

Action Types

Inject Instruction

Change Tool Candidates

Create a Dynamic Behavior Set

Create a dynamic behavior set

List Dynamic Behavior Sets

Get dynamic behavior sets

Search Dynamic Behavior Sets

Search dynamic behavior sets

Update a Dynamic Behavior Set

Update a dynamic behavior set

Delete a Dynamic Behavior Set

Delete a dynamic behavior instruction

Get Invocations

Get dynamic behavior invocations

Create a Version

Create a new version of a dynamic behavior set.

Get Versions

Get dynamic behavior set versions

Related