Events

When creating or interacting with conversations, the API responds with an NDJSON stream of events. This page summarizes the event types and how to use them.

Event Types

Event	type	Description
ConversationCreatedEvent	conversation-created	Contains the conversation_id for subsequent calls.
UserMessageAvailableEvent	user-message-available	Present when initial_message is provided; may represent a user message or an external event.
NewMessageEvent	new-message	Streaming message chunks from the agent (text or voice).
InteractionCompleteEvent	interaction-complete	Indicates the current interaction completed successfully.
ErrorEvent	error	Indicates an internal error; the interaction is rolled back.
CurrentAgentActionEvent	current-agent-action	Emitted only when the current_agent_action_type query parameter is set.

Important Notes

• Persist conversation_id from conversation-created.

• Continue reading until interaction-complete.

• Handle error events; nothing from that interaction is persisted.

Understanding Agent Actions

CurrentAgentActionEvent reveals agent behavior during generation.

Dynamic Behavior Triggered

Emitted when a dynamic behavior is triggered.

{
  "type": "current-agent-action",
  "action": {
    "type": "dynamic-behavior-triggered",
    "dynamic_behavior_set_version_info": ["<DYNAMIC-BEHAVIOR-SET-ID>", 3]
  }
}

Use this as a trigger to evaluate metrics and drive business workflows.

System Integration Flow

1. Capture dynamic_behavior_set_version_info when the event appears.

2. Map behavior IDs to the metrics you want to compute in your system.

3. Evaluate metrics and act (route, escalate, create tickets, store results).

Retrieve Dynamic Behavior Set Versions

Get dynamic behavior set versions

get

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

nullOptional

limitinteger · min: 1 · 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

or

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

HTTPcURLJavaScriptPython

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": "2025-10-11T15:10:49.305Z",
      "updated_at": "2025-10-11T15:10:49.305Z",
      "dynamic_behavior_set_id": "text",
      "version": 1,
      "conversation_triggers": [
        "text"
      ],
      "action": {
        "type": "text",
        "instruction": "text",
        "overrides_instructions": true
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Compute Metrics

Evaluate metrics

post

Evaluate the specified metrics for the given conversation, optionally up to the specified interaction.

Permissions

This endpoint requires the following permissions:

• Metric:EvaluateMetric for the metrics.
• Metric:GetMetricEvaluationResult for the metric results.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

metric_idsstring[] · min: 1 · max: 10Required

The IDs of the metrics to evaluate.

conversation_idstringRequired

The ID of the conversation to evaluate the metrics for.

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

evaluate_to_interaction_idany ofOptional

If specified, only messages up to (and including) this interaction will be evaluated.

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

or

nullOptional

Responses

200

Succeeded.

application/json

400

The conversation has no interactions.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, conversation, interaction, or metric is not found.

422

Invalid request path parameter or request body failed validation.

429

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

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

POST /v1/{organization}/metric/evaluate 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: 84

{
  "metric_ids": [
    "text"
  ],
  "conversation_id": "text",
  "evaluate_to_interaction_id": "text"
}

{
  "metrics": [
    {
      "metric_id": "text",
      "name": "text",
      "value": 1,
      "references": [
        "text"
      ],
      "justification": "text"
    }
  ]
}

curl --request POST \
  --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/metric/evaluate' \
  --header 'Authorization: Bearer <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "metric_ids": ["metric_id_1", "metric_id_2"],
    "conversation_id": "<CONVERSATION-ID>",
    "evaluate_to_interaction_id": "<INTERACTION-ID>"
  }'