Published queries and releases

A published query is a project resource with a defined input/output contract and release. Its bindings can require additional named read grants. queries:execute alone does not bypass those grants or install its data sources.

Execute

Prepare a published query, its project/query UUIDs and a scoped key. This request assumes the query contract has no required input fields; replace input with the fields required by your actual query.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input":{},"options":{"limit":10,"offset":0}}' \
  "https://platform.semogram.com/api/v1/projects/$SEMOGRAM_PROJECT_ID/queries/$SEMOGRAM_QUERY_ID/execute"

Use ?version=1 to request numeric release version 1; omit it for the service's selected release. The /ontology/queries/{queryId}/execute path is an alias. This is a REST body, not a JSON-RPC tool invocation.

HTTP 200 means succeeded; 202 means result work is pending. Inspect status, data and metadata. Continue using returned job/cursor information as described in pagination. Input defaults to {} and execution options have server defaults; supplying an empty input still fails if the published query requires fields.

Query authoring and publishing

The ontology query collection supports GET/POST with queries:read / queries:write; detail supports GET/PUT/DELETE. Authoring validates the query against ontology bindings and its contracts. Releases GET requires queries:read; POST requires queries:publish and a permitted accountable publisher, accepting the expected query version UUID. PATCH retires a numeric release version.

A query version UUID and a release number represent different stages. Editing a query does not silently change a pinned consumer release. Retiring a release is an intentional consumer-facing change.

Stop a pending result job

DELETE /projects/{projectId}/queries/{queryId}/jobs/{jobId} requires queries:execute. Only the calling key's active job in that workspace/project/query can be canceled. Completed, failed or canceled jobs are not active cancellation targets; expired results can return 410. There is no GET handler on this job route: use the execution continuation flow to retrieve results.

SPARQL

GET/POST /projects/{projectId}/ontology/sparql expose the semantic consumer interface under workspace semantic API mode and authorization checks. This is not a replacement for publishing a query contract. Enable only the intended mode and use the SPARQL contract described in the ontology documentation; writes remain governed.

SPARQL request example

For an authorized project with the semantic consumer read mode enabled, this bounded request asks for one triple from the supplied project graph:

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  -H 'Content-Type: application/sparql-query' \
  --data-binary 'SELECT ?subject ?predicate ?object WHERE { ?subject ?predicate ?object } LIMIT 1' \
  "https://platform.semogram.com/api/v1/projects/$SEMOGRAM_PROJECT_ID/ontology/sparql"

SPARQL accepts raw application/sparql-query or application/sparql-update POST bodies, or form encoding; this route does not accept the published-query JSON body. GET supports query reads only. External graph parameters are disabled and request text is capped at 1 MB. Updates require POST, write mode and the applicable governed authorization.