Custom destination

What this endpoint does

A custom destination endpoint selects where a custom writer sends pipeline output. Its supported formats, write modes and retry behavior come from your installed package implementation.

Directions and supported operations

This example is Egress only: Semogram → private service, using a custom write capability and write contract. It does not provide source reads or ontology storage. Its supported mutations and atomicity must be declared by the writer and enforced by the service; a destination does not inherit Iceberg source-write receipts or snapshot checks.

Plugin used

This scenario uses a custom write capability, not an existing named internal plugin. The endpoint stores selectors, not implementation code. For additional package-authoring details, see custom plugins.

What you need

You need a Semogram account with workspace access and permission to manage the required resources, the receiving service’s write API contract, credentials and a dedicated test dataset. Package creation and installation steps are below.

Example setup

For this scenario the custom writer implements append into a named dataset. Installation configuration holds service URL/auth; the write target declares required dataset and writeMode, with writeMode restricted to append. These example fields must exist in your package's actual published contract.

Implement the real destination writer lifecycle, failure reporting and cleanup. Do not declare upsert, overwrite, rollback or exactly-once behavior unless the receiving implementation and tests provide it.

Here vendor.verified_orders is the chosen Semogram endpoint name and vendor is its namespace. test_verified_orders is a dedicated dataset in the receiving service. Provision that test dataset using the service's tools before the first write. Prepare two input rows with known IDs so you can compare output.

Prepare and install the custom plugin

1. Open Plugins in the workspace and start custom plugin creation.
2. Describe the service's real authentication, operation, target fields and response/write behavior. Supply service documentation and a test fixture without exposing credentials.
3. Generate the package and run sandbox validation. Review its actual runtime exports, target schema, failure handling and fixture result; a manifest alone cannot implement the operation.
4. Publish the reviewed package to the workspace catalog and install its matching capability.
5. Configure the service URL and auth on the installation and run its supported check. Choose that installed capability when creating the endpoint below.

This example assumes the resulting package implements the exact target fields shown here. It does not supply a ready-made vendor connector. If your package's contract differs, use its real fields instead.

Use the assistant

Ask for a destination endpoint named vendor.verified_orders using the installed custom write capability, dataset test_verified_orders and append mode. Review the selected capability and target before saving.

Configure manually

Choose Edit manually in workspace endpoint creation. Select destination role, the custom write capability, write contract and namespace vendor.

Create the endpoint described on this page using these settings:
name: <ENDPOINT_NAME_FROM_THIS_EXAMPLE>
namespace: <ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>
role: destination
contractKind: write
target / dataset: test_verified_orders
target / writeMode: append
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": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
  "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
  "role": "destination",
  "contractKind": "write",
  "target": {
    "dataset": "test_verified_orders",
    "writeMode": "append"
  },
  "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
      "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
      "role": "destination",
      "contractKind": "write",
      "target": {
        "dataset": "test_verified_orders",
        "writeMode": "append"
      },
      "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

Describe the receiving dataset and owner. Configure formats according to the writer contract, then save. Keep credentials on the installation.

Verify the endpoint

1. Prepare a two-row CSV with columns order_id,total and rows 1,120.00 and 2,75.50. Upload it as a test dataset in this workspace and select its managed source endpoint.
2. In a workspace project, open Pipeline Studio. Connect an ingress node referencing that uploaded dataset to an egress node referencing the custom destination above.
3. Inspect the receiving dataset, append policy and caller permissions, validate the pipeline, save a version and execute once.
4. Inspect the run and use the receiving service's own read/admin interface to confirm exactly these two records arrived. A destination does not become readable merely because the same package implements writes.

Use a tiny known fixture in a pipeline targeting the test dataset. Review applicable policy and permissions before executing. Inspect receiving records, types, counts and returned errors, as well as the pipeline run.

Test retries and partial failure in the dedicated environment. With append mode a retry may duplicate data unless the implementation provides tested idempotency. Do not use a connection check as a substitute for this write test.

Manage the endpoint

Review consumers before changing datasets or upgrading the writer. Rotate credentials on the installation. Keep test and production targets separate and verify production access through the intended authorization flow.

FAQ

Does this support durable source-write MCP tools?

A custom destination writer does not automatically implement the Iceberg-backed source-write/action runtime. See write access.

Can I add upsert by changing the endpoint target?

Only if the published contract and runtime implement it. A target setting cannot supply missing writer behavior.

Where do I implement the package?

Follow custom plugins, including sandbox validation, review, publication and installation. The endpoint configures the installed implementation; it does not contain connector code.