# Terminology Mapping

The Amigo platform documentation and the REST API use different names for many of the same concepts. The platform documentation uses conceptual names optimized for understanding the system's architecture and purpose. The API uses precise technical names that reflect internal data structures and implementation.

This page provides a complete mapping between the two naming systems.

{% hint style="info" %}
**Classic API** - These terminology mappings apply to Classic API endpoints and schemas.
{% endhint %}

{% hint style="info" %}
**Why the names differ.** Platform documentation describes *what* each component does and how it fits into the overall system. The API names reflect *how* each component is implemented and stored. For example, "Context Graph" conveys the concept of a graph of conversational states and transitions, while `service_hierarchical_state_machine` describes the underlying data structure.
{% endhint %}

## Core Concept Mapping

| Platform Docs Term    | API Name                           | Endpoint Prefix                                    | Description                                                                                |
| --------------------- | ---------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Context Graph**     | Service Hierarchical State Machine | `/organization/service_hierarchical_state_machine` | The graph of states and transitions that defines an agent's conversational behavior        |
| **Actions**           | Tools                              | `/tool/`                                           | Versioned executable capabilities that agents invoke to perform work                       |
| **Dynamic Behaviors** | Dynamic Behavior Sets              | `/dynamic_behavior_set/`                           | Runtime events emitted during conversations for external system integration                |
| **Agent Core**        | Agent                              | `/organization/agent`                              | The agent configuration and versioned deployments                                          |
| **Evaluations**       | Metrics + Simulations              | `/metric/` + `/simulation/`                        | Quality measurement (metrics) and automated testing (simulations) of agent behavior        |
| **Agent Forge**       | CLI tool (`forge`)                 | Uses existing API endpoints                        | Command-line tool for development workflows (scaffold, publish, test)                      |
| **Side-effect State** | ToolCallState                      | Schema name in OpenAPI                             | A Context Graph state type where the agent generates parameters for a designated tool call |

## Evaluation Sub-Components

The platform concept of "Evaluations" spans two distinct API resource types:

| Platform Docs Term                    | API Resource                                                              | Key Endpoints                                                                                                                                                      |
| ------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Metrics** (quality criteria)        | Metric                                                                    | `POST /metric/`, `POST /metric/evaluate`, `GET /metric/metric_evaluation_result`                                                                                   |
| **Simulations** (automated test runs) | Simulation Persona, Scenario, Unit Test, Unit Test Set, Unit Test Set Run | `POST /simulation/persona/`, `POST /simulation/scenario/`, `POST /simulation/unit_test/`, `POST /simulation/unit_test_set/`, `POST /simulation/unit_test_set_run/` |

## Context Graph State Types

Within a Context Graph (API: `service_hierarchical_state_machine`), the following state types are defined:

| State Type       | API Schema Name   | Purpose                                             |
| ---------------- | ----------------- | --------------------------------------------------- |
| Action State     | `ActionState`     | Executes tools and evaluates exit conditions        |
| Decision State   | `DecisionState`   | Routes conversation flow based on conditions        |
| Reflection State | `ReflectionState` | Generates agent reasoning or summaries              |
| Tool Call State  | `ToolCallState`   | Generates parameters for a specific tool invocation |

{% hint style="warning" %}
**Platform API:** The voice agent supports three state types: Action, Decision, and Annotation. Recall, Reflection, and ToolCall states are Classic API features only and are not available in the Platform API's context graph engine.
{% endhint %}

## Memory System Terms

| Platform Docs Term       | API Concept                | API Endpoint                       |
| ------------------------ | -------------------------- | ---------------------------------- |
| **Raw Transcripts**      | Conversation Messages      | `GET /conversation/{id}/messages/` |
| **Extracted Memories**   | User Memory                | `GET /user/{user_id}/memory`       |
| **Episodic User Models** | (Internal)                 | No direct API access               |
| **Global User Model**    | User Model                 | `GET /user/{user_id}/user_model`   |
| **Additional Context**   | `additional_context` field | `POST /user/{requested_user_id}`   |

See [Memory Architecture & API Mapping](https://docs.amigo.ai/developer-guide/operations/reference/memory-architecture) for details on how to work with each layer.

## Deployment & Configuration Terms

| Platform Docs Term | API Name            | Notes                                                                        |
| ------------------ | ------------------- | ---------------------------------------------------------------------------- |
| **Environment**    | Version Set         | Named deployment configuration (`release`, `staging`, etc.) on a service     |
| **Service**        | Service             | A configured AI experience -- the term is the same in both contexts          |
| **Organization**   | Organization        | The top-level tenant boundary -- the term is the same in both contexts       |
| **Role**           | Role                | RBAC role defining user permissions -- the term is the same in both contexts |
| **Webhook**        | Webhook Destination | Configured endpoint that receives event notifications                        |

## Where to Find Each in the API

For quick reference, here is every major resource and its base path under `/v1/{organization}/`:

| Resource             | Base Path                                          |
| -------------------- | -------------------------------------------------- |
| Organization         | `/organization/`                                   |
| Agent                | `/organization/agent`                              |
| API Key              | `/organization/api_key/`                           |
| Context Graph        | `/organization/service_hierarchical_state_machine` |
| User Dimensions      | `/organization/user_dimensions/`                   |
| User                 | `/user/`                                           |
| Service              | `/service/`                                        |
| Conversation         | `/conversation/`                                   |
| Tool (Action)        | `/tool/`                                           |
| Dynamic Behavior Set | `/dynamic_behavior_set/`                           |
| Metric               | `/metric/`                                         |
| Role                 | `/role/`                                           |
| Simulation           | `/simulation/`                                     |
| Webhook Destination  | `/webhook_destination/`                            |
| Admin                | `/admin/`                                          |

## Tips for Reading the Documentation

* When the platform documentation mentions "Context Graph," look for endpoints containing `service_hierarchical_state_machine` in the API.
* When it mentions "Actions," look for `/tool/` endpoints.
* When it mentions "Evaluations," you likely need both `/metric/` and `/simulation/` endpoints.
* The [OpenAPI spec](https://api.amigo.ai/v1/openapi.json) is the single source of truth for exact endpoint paths, parameters, and response schemas.