Skip to content
omnismith docs

Create and Edit Entities

An Entity represents an active data record instantiated from a specific Template (e.g. a specific server prod-app-01, a customer ACME Corp, or a ticket #104).

1. Creating an Entity in the UI

Section titled “1. Creating an Entity in the UI”
  1. Navigate to Workspace via the navigation launcher.
  2. Select your target template from the Template Gateway (e.g. Server Node).
  3. Click + Create Entity.
  4. The dynamic entry form renders all attached attributes:
    • Dimensions: Text fields, dates, flags, and dropdown selection lists.
    • Metrics: Initial numeric values (e.g. Initial CPU % or Balance).
    • References: Searchable dropdowns pointing to target entities.
  5. Click Save.

Record details for a server: attribute group sections on the left, and a side rail with a Charts summary and History on the right

2. Entity Detail Workspace Tabs

Section titled “2. Entity Detail Workspace Tabs”

When you select an entity from the search list, the detail workspace provides three dedicated tabs:

  • Attributes: View and edit the current value of every dimension, metric, list option, and reference link. Fields are organized into structured section cards based on the template’s Attribute Groups (see the screenshot above), displaying section icons, custom headings, and responsive 1 or 2-column layouts. A side rail next to the form summarizes the record: a Charts summary of its key metrics (see Metrics Summary), its latest History entries, and any pending Scheduled Automations.
  • History: Review the complete immutable audit change log of every edit, detailing what changed, when, and by whom.
  • Chart: Analyze interactive time-series plots for numeric metric attributes over historical time windows.

3. Dynamic Field Validation

Section titled “3. Dynamic Field Validation”

Omnismith automatically validates attribute inputs on save:

  • Required Fields: Ensures mandatory dimensions and references are populated.
  • Data Type Safety: Enforces numeric ranges, valid date formats (YYYY-MM-DD), ISO timestamps, and strict List options.
  • Reference Integrity: Verifies that referenced target entities exist and are active.

4. Programmatic Ingestion via Slugs & REST API

Section titled “4. Programmatic Ingestion via Slugs & REST API”

Omnismith allows external systems, background agents, and CI/CD pipelines to create and update entities using project-unique slugs:

Creating an Entity Using Slugs

Section titled “Creating an Entity Using Slugs”

Post directly to /v1/entities/template/{template} specifying the template slug in the URL path and an attributes map in the request body:

Terminal window
curl -X POST "https://api.omnismith.io/v1/entities/template/server_node" \
  -H "Authorization: Bearer omni_live_secret_key_12345" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "hostname": "web-prod-03",
      "cpu_usage": 72.4
    }
  }'

Reading Entities: Compact and Verbose Attribute Values

Section titled “Reading Entities: Compact and Verbose Attribute Values”

By default a read returns attribute_values as a compact object mapping each attribute slug to its display value. Attributes without a slug are keyed by their UUID, and attributes whose value is empty are omitted. List, reference and file attributes show their label (list option label, referenced entity display value, original filename); the ids behind those labels come alongside in list_item_ids, reference_entity_ids and file_ids, keyed the same way. Writes and filters take those ids, not labels.

Terminal window
curl -X GET "https://api.omnismith.io/v1/entities/{entityId}" \
  -H "Authorization: Bearer omni_live_secret_key_12345"
{
  "id": "019fe207-38eb-7182-9a5f-70cdaeea34f2",
  "template_slug": "server_node",
  "attribute_values": {
    "hostname": "web-prod-03",
    "cpu_usage": "72.4",
    "status": "Online",
    "owner_team": "Platform"
  },
  "list_item_ids": {
    "status": "019fe207-38eb-7182-9a5f-70cdaeea3a01"
  },
  "reference_entity_ids": {
    "owner_team": "019fe207-38eb-7182-9a5f-70cdaeea3b07"
  },
  "file_ids": {}
}

Pass ?verbose=true when you need every attribute’s raw value and label side by side, including empty ones. attribute_values then becomes an array with one item per attribute and the id maps are omitted:

Terminal window
curl -X GET "https://api.omnismith.io/v1/entities/{entityId}?verbose=true" \
  -H "Authorization: Bearer omni_live_secret_key_12345"
{
  "id": "019fe207-38eb-7182-9a5f-70cdaeea34f2",
  "template_slug": "server_node",
  "attribute_values": [
    {
      "id": "019fe207-38eb-7182-9a5f-70cdaeea3001",
      "slug": "hostname",
      "value": "web-prod-03",
      "custom_value": "web-prod-03",
      "reference_entity_id": null
    },
    {
      "id": "019fe207-38eb-7182-9a5f-70cdaeea3002",
      "slug": "status",
      "value": "019fe207-38eb-7182-9a5f-70cdaeea3a01",
      "custom_value": "Online",
      "reference_entity_id": null
    }
  ]
}

The same verbose flag is accepted in the request body of POST /v1/entities/search/{template} and POST /v1/entities/semantic-search.