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 run 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.

Trigger Evaluation Flow

Typical Lifecycle

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

Rate Limits

Endpoint	Limit
Create a set	200 requests per minute
List sets	500 requests per minute
Search sets	50 requests per minute
Update a set	500 requests per minute
Delete a set	500 requests per minute
Get invocations	50 requests per minute
Create a version	200 requests per minute
Get versions	1000 requests per minute

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",
      "tool_name": "drug_interaction_lookup",
      "version_constraint": ">=1.0.0",
      "additional_instruction": "Use this tool to look up drug interactions",
      "audio_fillers": ["Let me look that up for you."],
      "audio_filler_triggered_after": 3,
      "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.

Each entry in tool_call_specs requires all of the following fields:

Field	Type	Description
tool_id	string	The ID of the tool
tool_name	string	An identifier of the tool displayed in the behavior set's description
version_constraint	string	A Python packaging version constraint for the tool
additional_instruction	string	Instruction supplied to the LLM in addition to the tool's description
audio_fillers	array	Audio fillers to play in audio mode if the tool is taking a long time
audio_filler_triggered_after	number	Seconds to wait before playing an audio filler
result_persistence	string	ephemeral, persisted-preferred, or persisted

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

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
      }
    ]
  }
}'

Python SDK

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}")

TypeScript SDK

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"
}

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-namestring · nullableOptional

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.

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

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'

Python SDK

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})")

TypeScript SDK

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})`);
});

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

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

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_activeboolean · nullableOptional

Whether the dynamic behavior set is active.

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-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more dynamic behavior sets to retrieve.

continuation_tokeninteger · nullableRequired

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

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-01-01T00:00:00.000Z",
      "creator": {
        "org_id": "text",
        "user_id": "text"
      },
      "updated_at": "2026-01-01T00:00:00.000Z",
      "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.

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

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

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_activeboolean · nullableOptional

Whether the dynamic behavior set is active.

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

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: []

Header parameters

x-mongo-cluster-namestring · nullableOptional

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.

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-01-01T00:00:00.000Z",
      "creator": {
        "org_id": "text",
        "user_id": "text"
      },
      "updated_at": "2026-01-01T00:00:00.000Z",
      "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.

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

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

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set to delete.

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

Header parameters

x-mongo-cluster-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

namestring · min: 1 · nullableOptional

The name of the dynamic behavior set.

applied_to_servicesstring[] · nullableOptional

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

is_activeboolean · nullableOptional

Whether the dynamic behavior set is active.

Responses

204

Succeeded.

No content

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.

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

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

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set to delete.

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

Header parameters

x-mongo-cluster-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

anyOptional

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. This is 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.

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

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

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-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more dynamic behavior invocations to retrieve.

continuation_tokeninteger · nullableRequired

A token to supply to the next request to retrieve the next page of dynamic behavior invocations. Only populated if has_more is True.

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-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "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-01-01T00:00:00.000Z",
      "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.

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

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

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set to delete.

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

Query parameters

versioninteger · nullableOptional

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.

Header parameters

x-mongo-cluster-namestring · nullableOptional

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.

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, "latest" for the most recent, or an inclusive range of version numbers separated by - (for example 2-5)
• limit (1-10, default 10)
• continuation_token (int, default 0)
• sort_by=+version|-version (repeatable)

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

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

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set.

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

Query parameters

versionstring · nullableOptional

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

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-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more dynamic behavior set versions to retrieve.

continuation_tokeninteger · nullableRequired

A token to supply to the next request to retrieve the next page of dynamic behavior set versions. Only populated if has_more is True.

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-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "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
}

Related

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