Terminology Mapping

Complete mapping between platform documentation names and REST API field names.

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.

Classic API - These terminology mappings apply to Classic API endpoints and schemas.

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.

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

Memory System Terms

Platform Docs Term	API Concept	API Endpoint
L0 Raw Transcripts	Conversation Messages	GET /conversation/{id}/messages/
L1 Extracted Memories	User Memory	GET /user/{user_id}/memory
L2 Episodic User Models	(Internal)	No direct API access
L3 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 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 is the single source of truth for exact endpoint paths, parameters, and response schemas.