Skip to main content

Hierarchy, Organizations, and Agents Guide

Llamalitica uses an organizational hierarchy model to facilitate large-scale agent management. This system allows you to separate testing environments, manage multiple workplaces, and control agent visibility in a centralized way.

Before you start

This guide explains the fundamental concepts of the organizational model. For detailed technical implementation, see the Integration Guide.

1. Core Concepts​

Organizations and Sub-organizations​

  • Parent Organization: The root entity (e.g. My Hospital Group). Acts as the control center and master agent repository.
  • Sub-organization: Entities that hang beneath the Parent (e.g. Madrid Medical Center, Valencia Branch).
  • Auto-provisioning: If you make an API request with an organization ID that does not exist, Llamalitica will create it automatically and link the user to that organization.

Agent Management​

Currently, creating, editing, and deleting agents is done on request to the Llamalitica team.

  • Local Agents: Reside in a specific organization and are only visible within it.
  • Inheritable Agents: Created in the Parent organization and, when marked as "inheritable", become available to all its sub-organizations.

Although Llamalitica allows creating infinite hierarchies (a sub-organization can have its own API Key and create its own "children"), we recommend a Horizontal Model.

Keeping all sub-organizations (centers) at a single level below the Parent simplifies agent management and data visibility.

3. Environment Strategy (Dev vs Prod)​

To manage development and production environments without separate servers, we use request headers:

  1. Beta / Testing Environment: The Parent organization is used. To access it, make the request without sending the X-ORGANIZATION header. This is where Llamalitica will configure new agents for your team to validate.

  2. Production Environment: Sub-organizations are used. Once an agent in the Parent is validated, we mark it as "inheritable" and it will automatically appear in the centers.

Centralized Maintenance

If we update an inheritable agent in the Parent, the change is reflected instantly across all centers, making global fixes and improvements easy.

4. Technical Integration​

Authentication and user location are resolved through three headers in API requests:

HeaderRequiredDescription
X-API-KEYYesThe organization's key (Parent or Sub-org).
X-USER-EMAILYesEnd-user identifier for traceability and context.
X-ORGANIZATIONOptionalThe internal ID of your sub-organization/center.

Example behavior​

  • Request without X-ORGANIZATION: The system places you in the organization that owns the API Key (ideal for internal testing and agent validation).

  • Request with X-ORGANIZATION: center-001: The system places you in that specific center. The user will see the center's own agents plus those inherited from the parent.

More technical details

See the Obtaining the User Token section in the Integration Guide for code examples in multiple languages.

5. API Keys and Access Levels​

Each organization (whether parent or child) can generate its own API Keys.

  • Parent Key: Can operate in the parent and create/manage first-level children.
  • Child Key: If a key is generated within a sub-organization, that key can only operate in that sub-organization and create "grandchildren" (one level below).
Recommendation

For most use cases, using the Parent API Key and differentiating centers via the X-ORGANIZATION header is sufficient, maintaining a flat and easy-to-monitor structure.