> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/operations/reference/terminology-mapping.md).

# 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. The names differ because platform documentation describes *what* each component does and how it fits into the overall system, while 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.

{% hint style="info" %}
**Classic API.** These terminology mappings apply to Classic API endpoints and schemas.
{% 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/`                           | Versioned sets of conversation triggers and actions that adjust agent behavior at runtime  |
| **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)                      |
| **Tool Call 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                   |
| Annotation State | `AnnotationState` | Injects a predefined inner thought and moves to the next state |
| Decision State   | `DecisionState`   | Routes conversation flow based on conditions                   |
| Recall State     | `RecallState`     | Retrieves user memory via static and dynamic queries           |
| 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 Platform API context graph engine supports four state types: Action, Decision, Annotation, and Data Collection. The same context graph runs on both voice and text channels. Recall, Reflection, and ToolCall states are Classic API features only, and Data Collection states are Platform API only.
{% 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](/developer-guide/operations/reference/memory-architecture.md) 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.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/operations/reference/terminology-mapping.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.