API Reference

SQL extensions

A map of Synapsor syntax that goes beyond ordinary SQL.

Overview

Synapsor supports ordinary SQL for tables and queries, plus agent-native extensions for sessions, storage profiles, branches, contexts, capabilities, governed memory, hybrid search, write proposals, settlement, replay, RBAC, and redaction.

Use this page as the high-level syntax map, then follow the linked topic docs for runnable examples.

When examples contain quoted values, distinguish user-defined strings from Synapsor-produced lookup ids. Names such as support.ticket_context are chosen by you; ids such as wrp://1 and evidence://bundle/1 come from response envelopes or system views.

Some HTTP routes and JSON specs keep /v1 or synapsor.agent/v1 version labels. Those are stable API-version labels, not hosted-product positioning or a V1 product label.

Developer notes

Use SQL extensions for Synapsor trust and workflow state, not for marketing labels.
Use hidden bindings whenever a value should come from the app/session rather than model output.
Use proposal and settlement syntax for risky writes.
Use replay and resource records when a decision must be audited later.

Custom syntax surface

Map

-- This is a syntax map, not one runnable script.
Session bindings:
  SET SESSION key = 'value'

Storage:
  CREATE TABLE ... PRIMARY KEY / UNIQUE / NOT NULL / REFERENCES ...
  CREATE TABLE ... WITH PROFILE ...
  ALTER TABLE ... SET RETENTION ...
  EXPLAIN STORAGE table
  COMPACT TABLE ... INTO COLUMNAR
  ARCHIVE TABLE ...

Branching:
  CREATE BRANCH, USE BRANCH, DIFF BRANCH, MERGE BRANCH, REVERT MERGE, DROP BRANCH

Agent catalog:
  CREATE/ALTER/DROP AGENT CONTEXT
  CREATE/ALTER/DROP AGENT CAPABILITY
  APPLY AGENT SPEC WITH JSON

Runtime:
  CREATE AGENT WORKFLOW
  BEGIN AGENT RUN
  INVOKE AGENT CAPABILITY ... IN AGENT RUN
  RECORD AGENT STEP
  RECORD AGENT GUARDRAIL EVENT
  HANDOFF AGENT RUN
  INTERRUPT AGENT RUN
  CHECKPOINT AGENT RUN
  END AGENT RUN
  EXPLAIN AGENT RUN
  CREATE EXTERNAL ACTION
  PROPOSE EXTERNAL ACTION
  CLAIM EXTERNAL ACTION
  CONFIRM EXTERNAL ACTION
  CREATE AGENT EVAL
  RUN AGENT EVAL
  SHOW AGENT EVAL FAILURES
  DIFF AGENT EVAL
  CREATE AGENT ADAPTER
  SHOW TRACE FOR AGENT RUN
  SHOW SLOW AGENT CAPABILITIES
  SHOW TOKEN USAGE
  SHOW APPROVAL LATENCY
  CREATE OBSERVABILITY SINK
  INVOKE AGENT CAPABILITY ... WITH JSON
  PROPOSE AGENT CAPABILITY ... WITH JSON
  PREVIEW/APPROVE/COMMIT/SETTLE WRITE
  SELECT ... FROM AGENT ACTIVITY
  INSPECT AGENT EVIDENCE

Memory:
  CREATE MEMORY POLICY
  REMEMBER FACT, PROPOSE MEMORY FACT, APPROVE/REJECT MEMORY PROPOSAL,
  SHOW MEMORY CONFLICTS, SUPERSEDE MEMORY FACT, RECALL MEMORY ... AS OF AGENT RUN,
  RETIRE FACT, FORGET FACT

Replay:
  AS OF VERSION/TIMESTAMP/AGENT RUN
  POST /v1/agent/runs/replay
  DIFF TABLE ... BETWEEN AS OF ... AND CURRENT

Security:
  CREATE ROLE, CREATE DEFAULT ROLE, GRANT, REVOKE
  CREATE SECURITY POLICY, CREATE REDACTION POLICY

System views:
  SELECT ... FROM synapsor_agent_activity
  SELECT ... FROM synapsor_evidence_bundles
  SELECT ... FROM synapsor_evidence_resources
  SELECT ... FROM synapsor_replay_records
  SELECT ... FROM synapsor_query_audit
  SELECT ... FROM synapsor_write_proposals
  SELECT ... FROM synapsor_agent_...
  SELECT ... FROM synapsor_table_...

Examples

sql

-- Session values come from your backend/auth context.
SET SESSION tenant_id = 'acme';             -- 'acme' is the authenticated tenant/account
SET SESSION principal = 'support_agent_17'; -- authenticated user/service identity
SET SESSION current_ticket_id = 'T001';     -- object id selected in your app

-- Context and capability names are developer-defined.
CREATE AGENT CONTEXT support.ticket_context  -- support.ticket_context is the context name
ROOT tickets AS ticket                       -- tickets is your table; ticket is local alias
LOOKUP ticket.id = SESSION current_ticket_id -- session-selected ticket row
BIND tenant_id FROM SESSION tenant_id        -- trusted tenant slot for filters/audit
OUTPUT SLOTS
  ticket_id AS ticket.id,                    -- output slot mapped from ticket.id
  subject AS ticket.subject
EVIDENCE ON;                                 -- record source rows/search hits

CREATE AGENT CAPABILITY support.answer_ticket -- capability name your app invokes
ARG question VARCHAR REQUIRED                 -- caller-provided WITH JSON field
HIDDEN tenant_id FROM SESSION tenant_id       -- trusted value, not prompt/model input
USE CONTEXT support.ticket_context            -- context created above
EXECUTION READ ONLY                           -- cannot stage or commit writes
RETURNS JSON '{"type":"object"}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only;

INVOKE AGENT CAPABILITY support.answer_ticket -- invokes the capability above
WITH JSON '{"question":"What should we answer?"}'; -- maps to ARG question