Create and Modify Catalog Entities¶

CLI and MCP can call owl.catalog.entity_create and owl.catalog.entity_modify. Upgrade the matching CLI, Registry, and AIAPI / Backend that provides these endpoints, then sync the catalog. Availability and permissions depend on the target site. Review the exact target and proposed changes before writing.

Resolve the Type, Team, and Entity¶

owl sync
owl exec owl.catalog.entity_type_query -p '{"page_size":20,"page_index":1}'
owl exec owl.workspace.member.group_list -p '{"search":"Platform"}'
owl exec owl.catalog.entity_query -p '{"entity_type":"service","name":"checkout-api"}'

Read the selected type's schemaDefine and customProperties. Supply all required type attributes. The top-level name does not replace a separate required attribute. The backend validates dynamic properties and relations.

entity_query requires entity_type. Use name for an exact name or search for fuzzy name, display-name, or URN search; never combine them. urn and filters narrow the result. Filters use catalog field syntax, not SQL/DQL. If both name and filters.name are supplied, they must agree.

The team tool returns group_uuid, name, and member_count, without pagination. owl.member.group_list is a compatibility alias. Set attributes.owner to a returned team name, not a UUID or person. The type defines its value shape. Team lookup is unavailable in free-edition workspaces.

Create and Partially Modify¶

Create requires request_id (UUID), entity_type, and name. Optional inputs are display_name, attributes, and relation_modes. Name is limited to 1024 characters; a nonblank display_name is limited to 256 characters and defaults to name when omitted. An existing identity or same-type name is not overwritten.

Modify requires request_id and the complete returned urn. Submit only the intended display_name, attributes, and relation_modes. Do not rename name, change type, write across workspaces, or copy an entire query item back. Use the top-level display_name.

Omitted fields remain unchanged. Objects merge recursively; ordinary arrays replace. An empty object does not clear a field, and null is not a deletion instruction. Manual writes can change the provider and lifecycle.

Use only relations declared by the actual type. Each submitted modify relation (depends_on, component_of, or components) requires a matching relation_modes entry: add appends and deduplicates; replace replaces the complete field; replace with an empty array clears it. Create defaults to replace. Targets must be existing same-workspace URNs and cannot reference the entity itself. Not every type supports components.

Write Results and Confirmation¶

Generate one UUID per new operation. Persist the tool, exact parameters, and identity/workspace context, without credential values. Use CLI -f json to inspect the business result. Process exit 0, HTTP 200, or outer success alone does not prove completion.

A successful result must include data.write_state=confirmed, the matching request_id, and an entity URN. changed=false can be a confirmed no-op. replayed=true does not mean another write. Confirmed includes entity readback and audit-task submission, not final audit storage.

Only can_retry_write=true permits a later call to retry the business write. Honor retry_after_ms (at most 30000 ms) and at most six total submissions. Reuse the original UUID and parameters. Other pending continuations confirm only. Do not automatically retry audit_unknown.

Backend state is retained for seven days per workspace, actual account, and request_id. After expiry, missing state, or identity/workspace changes, query and reconcile first. An old UUID is not permanent duplicate protection. One tool call does not poll or resend a business write automatically.