Data Model

Managed data that the agent creates automatically, plus the REST API for direct access.

How data works in Galadri

The agent automatically creates and maintains structured records as users interact. When someone says "I have a 2022 Honda Civic," the agent creates a vehicle record. When they book an oil change, a milestone and schedule entry appear. No schema design, no migrations, no manual writes needed.

Each end user gets their own scoped data: vehicles, documents (insurance, registration, receipts), milestones (service events, maintenance), and schedules (upcoming appointments). All of this is queryable through the REST API and manageable through the manage-data tool.

The manage-data layer works across six table families: end_users, vehicles, vehicle_groups, documents, milestones, and schedules. The sections below describe what each table is for so your own code and agents do not write the wrong kind of record.

Every conversation automatically loads the user's current vehicles, upcoming schedules, recent milestones, and documents into the agent's context. The agent just knows what the user has. This is not a retrieval step you configure. It happens automatically.

Real-time data events

When the agent creates, updates, or deletes data, your client receives a data_saved event via the SSE stream. This lets your UI update in real time without polling.

The event contains a mutations array. Each mutation includes the action that was performed, the table that was affected, and the full record after the change.

{
  "type": "data_saved",
  "mutations": [
    {
      "action": "create",
      "table": "vehicles",
      "record": {
        "id": "a1b2c3d4-...",
        "year": 2022,
        "make": "Honda",
        "model": "Civic",
        "trim": "EX",
        "odometer_km": 34500,
        "created_at": "2026-03-31T14:22:00Z"
      }
    }
  ]
}

Handle this event on the client to keep your UI in sync as the agent works:

for (const line of lines) {
  if (!line.startsWith("data: ")) continue;
  const payload = line.slice(6);
  if (payload === "[DONE]") break;

  const event = JSON.parse(payload);

  if (event.type === "data_saved") {
    for (const mutation of event.mutations) {
      switch (mutation.table) {
        case "vehicles":
          refreshVehicleList(mutation.record);
          break;
        case "schedules":
          addToCalendar(mutation.record);
          break;
        case "milestones":
          updateServiceHistory(mutation.record);
          break;
      }
    }
  }
}

REST API Reference

Galadri stores structured data on behalf of your application's users. All data is scoped to your organization and a specific end user. Data can be created and managed in two ways:

• Via the AI agent — The manage-data tool lets agents create, read, update, list, and delete records through natural conversation.
• Via REST endpoints — Use the Users, Vehicles, Vehicle Groups, Documents, Milestones, Schedules, Sessions, and Session Messages endpoints for direct programmatic access.

Manage-data Table Guide

Communication continuity records

Galadri also maintains communication-specific records outside the manage-data tables above. These are runtime continuity tables for email, SMS, and phone workflows, not user-authored business objects.

End Users

End users are your application's users. Each end user gets their own scoped data. Users are identified by the end_user_id you provide in chat requests. If the user does not exist, one is created automatically.

Create or update an end user. If a user with the same external_id already exists in your organization, it is updated (upsert).

List end users with filtering, sorting, and pagination.

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "external_id": "user-123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "city": "Phoenix",
      "state": "AZ",
      "timezone": "America/Phoenix",
      "distance_unit": "mi",
      "created_at": "2026-03-20T10:30:00Z",
      "updated_at": "2026-03-20T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Vehicles

Create a vehicle for an end user. The user_id field is your application's external ID for the end user (the same value you pass as end_user_id in chat requests).

List vehicles for an end user. The user_id query parameter is required.

Sessions

List chat sessions. Sessions are created automatically by the chat endpoint. Use PATCH /v1/sessions/:id to update hidden or unread, DELETE /v1/sessions/:id to soft-delete, and GET /v1/sessions/:id/messages to read messages.

Vehicle Groups

Vehicle groups let users organize vehicles into named collections (e.g., "Fleet A", "Family cars"). Groups are managed through the manage-data tool in chat or through the Vehicle Groups REST endpoints.

Documents

Documents store metadata about files associated with vehicles or end users (receipts, insurance cards, registration papers, etc.).

Milestones

Milestones track service events, maintenance, and other vehicle lifecycle events.

A milestone can begin as an upcoming due item and later be updated with completion details when the work actually happens. Agents should prefer updating a matching open milestone before creating a duplicate completion record.

Schedules

Schedules represent upcoming appointments, events, and automated communications. A schedule can be a simple calendar entry or an AI-triggered action that sends reminders via email, SMS, voice call, or webhook.

CRUD via Chat

Agents with the manage-data tool can create, read, update, list, and delete records in six table families. end_users is profile-scoped to the current user, while the other tables create separate records. The agent issues a tool call with the manage-data slug inside the batched actions:

{
  "actions": [
    {
      "tool": "manage-data",
      "args": {
        "action": "create",
        "table": "vehicles",
        "data": {
          "year": 2020,
          "make": "Toyota",
          "model": "Camry",
          "trim": "SE",
          "vin": "4T1BF1FK5LU123456",
          "odometer_km": 72420
        }
      }
    }
  ]
}

Available actions:

The data_saved Event

When the agent creates or updates data, the stream emits a data_saved event with the full record plus mutation metadata. Use this to update your UI in real-time without polling.

// In your SSE handler
if (event.type === "data_saved") {
  for (const mutation of event.mutations) {
    const changedFields = mutation.changedFields || [];

    if (mutation.table === "vehicles" && mutation.action === "create") {
      // Add the new vehicle to your UI
      addVehicleToList(mutation.record);
    }
    if (mutation.table === "schedules" && mutation.action === "create") {
      // Show the new appointment in the calendar
      addToCalendar(mutation.record);
    }
    if (mutation.action === "update") {
      // Optionally show a compact diff card using changedFields
      showDataMutationCard(mutation.record, changedFields);
    }
  }
}

Data Access Permissions

Each agent can be configured with a data access level that controls what the manage-data tool can do. See Data Access for details.

System Fields

Every record includes these auto-managed fields. You do not need to set them when creating records.