Publish and manage releases
Stabilize reviewed query logic and understand dependency checks
Saving a query creates or updates authoring state. Publishing creates a released contract for consumers. Executions use published releases, not whichever YAML happens to be in an open editor.
Publish exactly what was reviewed
You need a Semogram account, project query authoring access and publication permission. In the UI, publication requires the appropriate organization owner/admin role. API callers require queries:publish; connected MCP callers require the matching permission.
Author a complete query against a compiled package with valid input/output object schemas and active bindings. Save the draft and inspect its current saved version UUID. Publish using that exact value; if the draft changed, reread and review it rather than retrying with an old expectedVersionId.
Open the query, inspect its YAML, validation and current version, then choose Publish. Check the created release number and status.
Inspect the selected query draft, its exact saved version, schemas and resolved bindings. Show validation and the intended released contract before publishing that version. If the draft changed, stop and rereview it.Use a workspace API key with queries:publish. Set SEMOGRAM_API_KEY in your shell and replace UUID placeholders with accessible resource IDs.
curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_UUID>/ontology/queries/<QUERY_UUID>/releases" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"expectedVersionId": "<REVIEWED_VERSION_UUID>"
}
JSON{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "query_publish",
"arguments": {
"projectId": "<PROJECT_UUID>",
"queryId": "<QUERY_UUID>",
"expectedVersionId": "<REVIEWED_VERSION_UUID>",
"idempotencyKey": "<UNIQUE_PUBLISH_KEY>"
}
}
}What the release keeps
The released contract stores query content, input/output schemas, the selected ontology identity/hash, resolved binding definitions and relevant endpoint contract hashes. It is more than a query name.
Execution checks that the ontology contract is still available/unchanged, relevant endpoint configuration still matches, and published bindings remain active. Current read policies are enforced; masking does not loosen merely because an older release was published. A release does not freeze live source records.
Changing the model or endpoint configuration can make a release unavailable until a new compatible release is published. Changing an author's draft does not silently rewrite existing releases. Withdrawal of a bound source/binding can prevent execution even if the query itself remains published.
Select, retire and inspect
HTTP execution can specify ?version=<RELEASE_NUMBER>; MCP query_execute accepts numeric version. Without an explicit version, inspect which eligible release is selected. A saved-version UUID is not a release number.
List releases through the UI, HTTP GET /ontology/queries/<QUERY_UUID>/releases (queries:read) or MCP query_release_list. Retire a release through supported UI, HTTP PATCH on that route with { "version": <NUMBER>, "status": "retired" } (queries:publish), or MCP query_release_retire using its discovered contract. Retirement prevents new use of that release; inspect pinned consumers first.
Update consumers deliberately
Forecasters can pin query releases. A newly published release does not automatically update every forecaster or saved consumer. Check pinned version, compatible input/output shape and actual execution before switching. Query releases, ontology definition versions and pipeline active versions must be reviewed separately.