Query API contract

SignalQL API is retrieval-only. It accepts SignalQL text plus execution context and returns structured evidence with metadata for interpretation layers.

Endpoint

POST /query

Request

{
  "signalql": "FROM entity(work_item) WHERE signal(risk_score) > 0.7 RETURN entity_id",
  "context": {
    "workspace": "acme-prod",
    "time_range": "last_30d"
  }
}

Response

{
  "data": [
    {
      "entity_id": "WI-123",
      "signal.risk_score": 0.84
    }
  ],
  "signals": [
    {
      "name": "risk_score",
      "source": "external",
      "version": "2026-05"
    }
  ],
  "metadata": {
    "signalql_version": "v0.2",
    "canonical_query": "FROM entity(work_item) WHERE signal(risk_score) > 0.7 RETURN entity_id, signal(risk_score)",
    "execution_plan_id": "plan_01H...",
    "deterministic": true
  }
}

Required API behavior

• Validate query grammar against declared SignalQL version.
• Normalize to canonical query order before execution.
• Return machine-readable execution metadata for auditability.
• Do not return interpreted outcomes (for example "this work item is blocked").

Non-goals

• No mutation endpoints in SignalQL core contract.
• No domain-pack interpretation in base response.