Requests and resource IDs

Use the production base https://platform.semogram.com/api/v1. In a self-hosted or local environment, substitute the platform origin that serves these routes. The documentation server is not the API server.

Path and body

Path placeholders such as {projectId} and {endpointId} mean UUIDs. Names, slugs and installed plugin discovery IDs are different identifiers. Workspace identity comes from the API key; do not try to switch it by supplying another workspace in JSON.

Send JSON bodies with Content-Type: application/json when a route accepts a body. GET filters belong in the query string. Use URL encoding for JSON filters and SPARQL text.

curl --fail-with-body --get \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  --data-urlencode 'name=Equipment' --data-urlencode 'limit=10' \
  'https://platform.semogram.com/api/v1/projects'

Interfaces are different

A platform form accepts fields; an assistant receives a natural-language instruction; MCP accepts tool arguments wrapped in a tool invocation. The HTTP API accepts the resource path and request body documented here. Sending tools/call JSON to a REST resource does not invoke an MCP tool.

Response handling

Inspect HTTP status before parsing the resource. Successful routes can return envelopes such as {projects, pagination}, {dataEndpoint}, {query} or a run detail. There is no universal data envelope. HTTP 201 means creation; HTTP 202 means accepted or still running, not complete.

Treat IDs returned by the server as authoritative. Preserve version IDs separately from resource IDs. Query release versions are positive integers; asset version IDs are UUIDs. Send a returned cursor unchanged rather than deriving one from an offset.

Changes and deletion

PATCH/PUT semantics depend on the resource. Key grants and member grants replace the supplied grant set; draft saving does not activate a version. Deletion can be rejected when active work or references make it unsafe. Do not interpret DELETE as a way to cancel execution.