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 describe service history or upcoming maintenance, milestone and schedule records appear. You can also read and write the same records directly through the REST API.

Each end user gets their own scoped data: vehicles, documents (insurance, registration, receipts), milestones (service events, maintenance), and schedules (upcoming appointments and automations). All of this is queryable through the REST API and can be maintained by agents during a chat session when data access is enabled.

Managed data covers six public table families: end_users, vehicles, vehicle_groups, documents, milestones, and schedules. The field lists below match Galadri's current write contract, with REST-only exceptions called out separately.

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

Reference arrays such as vehicle_ids accept up to 100 UUIDs per field. Referenced records must belong to the same organization and, when the endpoint is scoped to a user, the same end user.

Real-time data events

When the agent creates or updates managed 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",
        "nickname": "Daily commuter",
        "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 Chat API - agents can create, read, update, list, and delete managed records through natural conversation, subject to the selected agent's data access settings.
• Via REST endpoints - use the Users, Vehicles, Vehicle Groups, Documents, Milestones, Schedules, Sessions, and Session Messages endpoints for direct programmatic access.

Managed Tables

Communication continuity records

Galadri also maintains communication-specific records outside the managed 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.

Refresh explicitly requested vendor-backed vehicle fields directly. targets is required so organizations without telematics credentials can request valuation without triggering a telemetry lookup.

{
  "targets": ["dtc_codes", "valuation"],
  "valuation": {
    "dealer_type": "independent",
    "zip": "02139"
  }
}

The response includes a refresh object keyed by requested target and the latest vehicle row after refresh attempts. The top-level status is success, partial_success, or error. Target execution failures are also returned inside the target result with status: "error". Mixed target outcomes return HTTP 200 with partial_success. If every requested target fails, Galadri returns HTTP 502 with status: "error". Authentication, validation, vehicle lookup, and credit failures use their normal non-200 status codes.

{
  "status": "success",
  "data": {
    "vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
    "refreshed_at_utc": "2026-04-28T21:35:00.000Z",
    "refresh": {
      "dtc_codes": {
        "status": "success",
        "data": {
          "source": "telemetry_snapshot",
          "dtc_codes": ["P0301", "P0420"],
          "last_dtc_update_utc": "2026-04-28T21:34:58.000Z"
        }
      },
      "valuation": {
        "status": "success",
        "data": {
          "estimated_dealer_retail_price_cents": 1875000,
          "vehicle_sync": {
            "status": "updated",
            "fields_synced": [
              "retail_valuation_cents",
              "last_valuation_update_utc",
              "valuation_source",
              "valuation_method"
            ]
          },
          "persistence": {
            "saved_to_vehicle_row": [
              "retail_valuation_cents",
              "last_valuation_update_utc",
              "valuation_source",
              "valuation_method"
            ],
            "not_saved_requires_your_judgment": [
              "valuation_insight",
              "time_to_sell_score"
            ]
          }
        }
      }
    },
    "vehicle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "dtc_codes": ["P0301", "P0420"],
      "last_dtc_update_utc": "2026-04-28T21:34:58.000Z",
      "retail_valuation_cents": 1875000,
      "valuation_source": "marketcheck_price",
      "valuation_method": "marketcheck_price"
    }
  }
}

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.

The hidden flag is a developer convenience for your own chat-history UI. It does not delete the session, remove it from the Sessions API, or hide it from the Galadri Console data browser.

Vehicle Groups

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

Group membership is canonical on the vehicle group record itself via vehicle_ids. Vehicles do not carry a mirrored inverse array of group IDs.

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.

Agent-managed Updates

Agents can maintain managed records during Chat API requests when data access is enabled.end_users is profile-scoped to the current user. The other managed tables create separate records scoped to the same user. Your application should not construct internal agent operations directly. Use the Chat API for conversational updates and the REST endpoints for direct writes.

Data Access Permissions

Each agent can be configured with a data access level that controls what it can read or change in managed data. See Data Access for details.

System Fields

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