Extending Slugs Across Templates and Entities for Deterministic API Workflows

Eliminate identifier resolution queries in automated ingestion pipelines. Omnismith extends project-unique slugs across templates and entities for deterministic API workflows.

The Problem with UUID-Only Ingestion

Automating entity management and metric ingestion requires continuous interaction with platform schemas. Prior to platform-wide slug support, writing data to Omnismith required external scripts to maintain or fetch UUIDv7 identifiers for attributes and templates.

Ingestion scripts and ETL jobs either hardcoded generated UUIDs across environments or executed pre-flight HTTP requests (GET /v1/templates, GET /v1/attributes) to resolve human-readable schema definitions into target UUIDs. This pattern added network latency, introduced points of failure during schema deployment across projects, and increased code complexity in stateless pipelines. Additionally, schema-aware AI Assistant workflows executing via Model Context Protocol (MCP) required extra context lookups to map user intents to internal platform identifiers before writing records.

Architecture of Universal Slug References

The extension of project-scoped slugs across attributes, templates, and entity write endpoints provides a deterministic mechanism for defining and populating structured records without initial lookup queries.

Attributes declare a project-unique string identifier during creation. Templates adopt a corresponding slug property and reference required attributes by attribute_slug during definition. When instantiating or updating entities, endpoints accept template_slug and attribute_slug parameters.

The ingestion pipeline resolves incoming slugs to underlying UUIDv7 primary keys during payload validation. Entity read endpoints support the ?attribute_key=slug query parameter to return attribute dictionary maps keyed by string slugs. The in-app AI Assistant leverages this interface through MCP tools, generating payload structures directly from schema definitions without intermediate identity resolution calls.

End-to-End API Sequence

The following sequence illustrates creating an infrastructure metric attribute, binding it to a compute template, instantiating an entity record, and reading the entity state using slugs.

1. Define a metric attribute with a slug identifier:

curl -X POST "https://api.omnismith.io/v1/attributes" \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CPU Utilization",
    "attribute_type": 1,
    "data_type": 1,
    "description": "Host CPU load percentage",
    "slug": "cpu_usage"
  }'

Response:

{"id":"019fe205-c125-735b-98bd-86851e8baf15"}

1. Bind the attribute to a template using slug and attribute_slug:

curl -X POST "https://api.omnismith.io/v1/templates" \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compute Node",
    "slug": "node",
    "category": "Infrastructure",
    "attributes": [
      {
        "attribute_slug": "cpu_usage",
        "default_value": null
      }
    ]
  }'

Response:

{"id":"019fe206-e9d6-7349-b628-f9e9474622a2"}

1. Instantiate an entity using template_slug and attribute_slug:

curl -X POST "https://api.omnismith.io/v1/entities" \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_slug": "node",
    "attribute_values": [
      {
        "attribute_slug": "cpu_usage",
        "value": "84.2"
      }
    ]
  }'

Response:

{"id":"019fe207-38eb-7182-9a5f-70cdaeea34f2"}

1. Retrieve the entity with slug-keyed attribute values:

curl -X GET "https://api.omnismith.io/v1/entities/019fe207-38eb-7182-9a5f-70cdaeea34f2?attribute_key=slug" \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "id": "019fe207-38eb-7182-9a5f-70cdaeea34f2",
  "template_id": "019fe206-e9d6-7349-b628-f9e9474622a2",
  "template_slug": "node",
  "created_at": "2026-08-08T15:39:11+00:00",
  "updated_at": "2026-08-08T15:39:11+00:00",
  "attribute_values": {
    "cpu_usage": {
      "value": "84.2",
      "custom_value": "84.2",
      "reference_entity_id": null,
      "attribute_id": "019fe205-c125-735b-98bd-86851e8baf15",
      "attribute_slug": "cpu_usage"
    }
  }
}

Technical Tradeoffs

Using string slugs introduces operational considerations regarding schema immutability and lookup runtime:

• Scope Uniqueness Constraints: Slugs are enforced as unique within the scope of a single project. Modifying an existing slug breaks downstream pipelines configured to send payloads with that string identifier.
• In-Memory Resolution Overhead: API requests containing slugs undergo an in-memory resolution step to map strings to backend PostgreSQL UUIDv7 primary keys prior to executing entity updates or time-series storage writes in TimescaleDB.
• Key Invariance: Underlying database entities retain fixed UUIDv7 primary keys. Internal foreign keys, append-only history logs, and time-series metrics maintain storage on UUID keys.

System Impact

Universal slug support across resources removes external state dependencies from automated pipelines. Scripts deploy and populate project schemas deterministically across environments using static configuration files. Integration layers and the schema-aware AI Assistant interact directly with readable keys while preserving relational storage speed and audit history tracking.

Comments

[Mikhail]

This is the mirror image of a resolution problem I've been dealing with — you're paying an upfront uniqueness cost (project-scoped slug constraints, an in-memory resolution step before every write) to guarantee a name always maps to exactly one thing. I'm on the other side of that trade: a codebase-intelligence MCP server where symbol names aren't enforced unique across the repo, so a lookup can silently resolve to the wrong definition when two files happen to share a function name.

Your "Scope Uniqueness Constraints" tradeoff is basically the other half of my bug — you get determinism by rejecting collisions at write time; I have to detect and rank them after the fact because the underlying symbol space was never constrained to begin with. Cheaper for you upfront, more work for me downstream. Makes me wonder whether a similar slug-style uniqueness constraint (scoped per-directory instead of per-project) would have been the better fix on my end instead of a ranking heuristic — trading a bit of author friction (can't reuse a name across modules) for the same guarantee you're getting here.

Good writeup — the slug-over-UUID trade for MCP tool-calling specifically (skipping the lookup round-trip before an agent can write) is a detail I hadn't considered for tool-facing APIs.