Fields and contracts

What these fields configure

An endpoint gives selected data a workspace name and binds it to an installed operation. The name is chosen in Semogram; the target identifies the table, collection, path or other data in the external system.

Plugin used

The selected capability determines target fields and supported operations. This page's destination example uses the Postgres write capability; Postgres installation is optional further reading.

What you need

Before applying fields, identify your workspace, installed capability and actual external target. For reads, verify source access; for destinations, verify the writer's supported mode and permissions. The UUIDs below are illustrative IDs and must be replaced with IDs from your workspace.

Data endpoints are the named read and write points workflows use. A source node reads from one; a destination node writes to one; the ontology store is one. Plugin installations own the connection — endpoints name concrete targets. See Endpoints and installations

Create endpoints in Data Endpoints, within a selected workspace. Projects in that workspace can reference them. Endpoints reference an installed capability through pluginCapabilityInstallationId The identity example below is a field fragment; the destination example is a creation payload with an illustrative workspace UUID. Supply the real workspace and capability installation when using it

Example identity

For illustration, imagine an existing orders table in your database. We choose orders as the Semogram endpoint name and sales as its grouping namespace. Neither label creates a database table.

Identity fields

Create the endpoint described on this page using these settings:
name: orders
namespace: sales
description: Order stream for renewal analytics. Owner: revenue ops.
target / schema: <ACTUAL_SCHEMA>
target / table: <ACTUAL_TABLE>
pluginCapabilityInstallationId: <INSTALLED_CAPABILITY_UUID>
Use the actual installed capability and the endpoint name/namespace selected in this example. Show the proposed direction, connection and target before saving. Keep credentials on the installation.

curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_ENDPOINT>" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "orders",
  "namespace": "sales",
  "description": "Order stream for renewal analytics. Owner: revenue ops.",
  "target": {
    "schema": "<ACTUAL_SCHEMA>",
    "table": "<ACTUAL_TABLE>"
  },
  "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "orders",
      "namespace": "sales",
      "description": "Order stream for renewal analytics. Owner: revenue ops.",
      "target": {
        "schema": "<ACTUAL_SCHEMA>",
        "table": "<ACTUAL_TABLE>"
      },
      "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

Role and contract

The UI offers Ingress, Egress and Materialization. The role and contract lists above include serialized API values; their presence in the enum does not mean every value is offered by the form or implemented by the selected capability. For readable capabilities with both contracts, Source contract offers Stream or Query.

The destination example below assumes an existing PostgreSQL table named forecast_scores in schema analytics. forecast_output is the endpoint name we choose; warehouse is its grouping namespace. The installed Postgres writer targets that table in append mode. This payload documents fields, not external database provisioning.

Create the endpoint described on this page using these settings:
name: forecast_output
namespace: warehouse
role: destination
contractKind: write
pluginCapabilityInstallationId: 22222222-2222-4222-8222-222222222222
target / schema: analytics
target / table: forecast_scores
target / writeMode: append
emits: parquet
Use the actual installed capability and the endpoint name/namespace selected in this example. Show the proposed direction, connection and target before saving. Keep credentials on the installation.

curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_ENDPOINT>" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "forecast_output",
  "namespace": "warehouse",
  "role": "destination",
  "contractKind": "write",
  "pluginCapabilityInstallationId": "22222222-2222-4222-8222-222222222222",
  "target": {
    "schema": "analytics",
    "table": "forecast_scores",
    "writeMode": "append"
  },
  "emits": "parquet"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "forecast_output",
      "namespace": "warehouse",
      "role": "destination",
      "contractKind": "write",
      "pluginCapabilityInstallationId": "22222222-2222-4222-8222-222222222222",
      "target": {
        "schema": "analytics",
        "table": "forecast_scores",
        "writeMode": "append"
      },
      "emits": "parquet",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

Schema hints

Trust and ownership

Forecasts built on low-trust targets deserve extra skepticism at dry-run

Write governance

Full catalog in Write policies. A saved destination is not proof that writes are authorized. Bind the applicable approved policy and check actor permissions before execution

Field limits and defaults

Names accept letters, numbers, dots, underscores, hyphens and colons. name is limited to 160 characters and namespace to 100. Description is limited to 1,000 characters. Freshness, owner team and format strings have a 100-character limit where supplied.

Creation requires workspaceId, name, namespace and a non-empty target. Defaults are source role, source_stream contract, medium trust, empty schema hints and parquet output. The selected capability's target schema adds operation-specific requirements. A contract enum value does not mean every capability implements it.

The installation and capability reference must belong to the same workspace. For external connectors, supply the actual installed capability ID; a null binding does not create an implementation. Writes and policy binding use their separately enforced operation paths.

Choosing well

• One endpoint per real target — share endpoints, version workflows
• Namespaces mirror systems, not teams: systems outlive reorgs
• Trust ranks get reviewed on a schedule, or every target quietly becomes medium and the rank means nothing