Getting started

Quickstart

Ship your first safe agent workflow on Synapsor in about 10 minutes.

Synapsor Cloud is currently in V2 controlled beta. The /v1 route prefix in the examples is the stable HTTP API namespace, not a V1 product label.

Choose your quickstart path

Default recommendation: start with Existing Postgres/MySQL if you already have an application database.

Existing Postgres/MySQL quickstart

Start here for most apps. Connect read-only, inspect schema, import selected tables/views, generate approved tools, run read-only, inspect evidence/query audit, then stage external write proposals as Synapsor review branches.

Write proposal quickstart

Learn the proposal path: evidence-backed row diffs, approval, Synapsor review branch or native branch depending on target, replay, and trusted writeback before a risky update reaches production.

Synapsor-native workflow quickstart

Use this when Synapsor stores the workflow data directly and you want real branch/merge operations inside Synapsor.

Which branch model will I use?Existing Postgres/MySQL quickstart uses Synapsor review branches and trusted writeback. Synapsor-native quickstart uses real Synapsor branch/merge. Both give agents a safe proposal path before production-visible data changes.

Request Free or Builder Trial access

Request controlled beta access. Free Controlled Beta is $0, invite-approved, hard-capped, and does not require a credit card. Builder Beta also requires invite approval; Builder invite setup starts a 14-day no-card trial, then continues at $20/month only when paid billing is active. Resources unlock only when billing is trialing or active.

Create a project

bash

# SYNAPSOR_SESSION_TOKEN comes from the logged-in console session.
# project_id is your own stable slug for this project.
curl -fsS https://synapsor.ai/v1/control/projects \
  -H "Authorization: Bearer $SYNAPSOR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"project_id":"acme-support","name":"Acme Support","plan":"free"}'

Create a database

bash

# project_id must match the project you created above.
# idempotency_key is caller-defined so retries do not create duplicate databases.
curl -fsS https://synapsor.ai/v1/control/databases \
  -H "Authorization: Bearer $SYNAPSOR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"project_id":"acme-support","name":"Support Sandbox","plan":"free","idempotency_key":"support-sandbox-001"}'

Create a database API key

bash

# database_id comes from the database creation response or console.
# The API key returned by this call becomes SYNAPSOR_API_KEY for app traffic.
curl -fsS https://synapsor.ai/v1/control/api-keys \
  -H "Authorization: Bearer $SYNAPSOR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"project_id":"acme-support","database_id":"db_acme_support_001","name":"quickstart-server","role":"developer"}'

Run SELECT 1

bash

# SYNAPSOR_API_KEY is the database API key created in step 4.
curl -fsS https://synapsor.ai/v1/sql \
  -H "Authorization: Bearer $SYNAPSOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"sql":"SELECT 1;"}'

Create tables

sql

-- tickets is the hot workflow table the capability will read and propose updates to.
CREATE TABLE tickets (
  id VARCHAR PRIMARY KEY,
  tenant_id VARCHAR NOT NULL,
  customer_id VARCHAR NOT NULL,
  subject VARCHAR,
  status VARCHAR,
  reviewer VARCHAR,
  resolution_note VARCHAR
) WITH PROFILE hot_state;

-- policy_chunks is searchable_knowledge because the context uses HYBRID(body).
CREATE TABLE policy_chunks (
  id VARCHAR PRIMARY KEY,
  tenant_id VARCHAR NOT NULL,
  title VARCHAR,
  body VARCHAR
) WITH PROFILE searchable_knowledge;

-- ticket_audit stores proposal/approval history; audit_log keeps it append-oriented.
CREATE TABLE ticket_audit (
  id VARCHAR PRIMARY KEY,
  tenant_id VARCHAR NOT NULL,
  principal VARCHAR,
  ticket_id VARCHAR,
  action VARCHAR
) WITH PROFILE audit_log;

-- Synapsor builds the retrieval index used by SEARCH ... USING HYBRID(...).
CREATE HYBRID INDEX policy_chunks_body_hidx
ON policy_chunks(body);

Set session values

These values come from your backend: tenant from the selected account/project, principal from the authenticated user or service identity, and current_ticket_id from the object the user is working on.

sql

SET SESSION tenant_id = 'acme';              -- trusted tenant value from your backend
SET SESSION principal = 'support_agent_17';  -- human/service identity for audit
SET SESSION current_ticket_id = 'T001';      -- app-selected ticket for this workflow

Create an agent context

sql

CREATE AGENT CONTEXT support.ticket_context  -- developer-defined context name
ROOT tickets AS ticket                       -- tickets is your table; ticket is the local alias
LOOKUP ticket.id = SESSION current_ticket_id -- current_ticket_id is set by your backend session
BIND tenant_id FROM SESSION tenant_id        -- trusted tenant scope copied into the context
BIND principal FROM SESSION principal        -- trusted actor for audit/evidence
SEARCH policy_chunks AS policy_hits USING HYBRID(policy_chunks.body) -- policy_hits is the retrieval step
  QUERY ARG question                         -- question comes from INVOKE/SDK arguments
  FILTER policy_chunks.tenant_id = SESSION tenant_id -- trusted tenant filter, not model text
  TOP 5                                      -- maximum policy chunks returned
OUTPUT SLOTS
  ticket_id AS ticket.id,                    -- output slot name mapped from ticket.id
  subject AS ticket.subject,
  status AS ticket.status
EVIDENCE ON;                                 -- record rows/search hits used by the capability

Create a read-only capability

sql

CREATE AGENT CAPABILITY support.answer_ticket_question -- developer-defined action name
DESCRIPTION 'Answer ticket questions using governed context and evidence'
ARG question VARCHAR REQUIRED                -- supplied by WITH JSON {"question": ...}
HIDDEN tenant_id FROM SESSION tenant_id      -- backend-owned trust boundary
HIDDEN principal FROM SESSION principal      -- backend-owned actor identity
HIDDEN current_ticket_id FROM SESSION current_ticket_id -- selected ticket id
USE CONTEXT support.ticket_context           -- context created in step 8
EXECUTION READ ONLY                          -- capability cannot stage or commit writes
RETURNS JSON '{"type":"object","properties":{"decision":{},"answer":{},"evidence_bundle":{}}}'
PROFILE MINIMAL                              -- compact response shape
INLINE EVIDENCE handles_only;                -- return compact evidence lookup ids, not bulky inline facts

Invoke the capability

The JSON field question is the caller-provided value for the capability's ARG question. Synapsor returns durable lookup ids for the run and evidence; store them with your app's ticket, invoice, order, or audit row.

sql

INVOKE AGENT CAPABILITY support.answer_ticket_question -- returns agent_run_id/evidence lookup ids
WITH JSON '{"question":"Can we waive this late fee?"}'; -- question maps to ARG question

CLI equivalent: synapsor invoke support.answer_ticket_question --project acme-support --db db_acme_support_001 --json '{"question":"Can we waive this late fee?"}'

Inspect evidence

The invocation response includes an evidence lookup id such as evidence://bundle/45. In a production app, store that id with the ticket, invoice, order, customer event, request id, and timestamp shown to a human reviewer. The SQL shell/session alias last_evidence points to the most recent record only while you are learning.

sql

READ RESOURCE 'last_evidence';      -- learning alias for newest returned evidence lookup id
READ RESOURCE 'last_evidence/hits';

-- In production, prefer the returned run/evidence/proposal ids stored with your app event.
-- If a reviewer only knows "the Acme ticket from yesterday", search by the app event
-- fields instead of scrolling agent sessions: object id, request_id, tenant/principal,
-- workflow, capability, query fingerprint, proposal/settlement id, and time window.
SELECT id, full_name, trace_id, evidence_id
FROM synapsor_agent_runs
WHERE trace_id = 'req_01HV...'            -- request_id stored beside ticket:T001 in your app
ORDER BY id DESC
LIMIT 10;

CLI equivalent: synapsor evidence get evidence://bundle/45 --project acme-support --db db_acme_support_001

Create and review a write proposal

sql

CREATE AGENT CAPABILITY support.propose_ticket_resolution -- stages writes instead of mutating main
DESCRIPTION 'Create a previewable ticket resolution proposal'
ARG ticket_id VARCHAR REQUIRED               -- caller-selected ticket id
ARG status VARCHAR REQUIRED                  -- proposed new status
ARG note VARCHAR REQUIRED                    -- proposed resolution note
HIDDEN tenant_id FROM SESSION tenant_id      -- trusted tenant guard
HIDDEN principal FROM SESSION principal      -- trusted reviewer/actor
USE CONTEXT support.ticket_context           -- reuses governed ticket/policy context
EXECUTION PROPOSAL                           -- creates wrp:// proposal instead of direct write
RETURNS JSON '{"type":"object","properties":{"proposal":{},"branch":{},"evidence_bundle":{}}}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only
WRITE PROPOSAL TARGET tickets                -- target table for the staged write
OPERATION UPDATE                             -- only UPDATE is allowed by this capability
LOOKUP id FROM ARG ticket_id                 -- maps tickets.id to the caller argument
TENANT tenant_id FROM BINDING tenant_id      -- target row must match trusted tenant binding
COLUMNS status FROM ARG status,              -- visible caller value
        reviewer FROM BINDING principal,     -- trusted session actor
        resolution_note FROM ARG note        -- visible caller value
AUDIT ticket_audit                           -- audit table for proposal events
SUMMARY TEMPLATE 'Resolve ticket {ticket_id}'; -- {ticket_id} resolves from ARG ticket_id

PROPOSE AGENT CAPABILITY support.propose_ticket_resolution -- returns proposal/evidence/branch lookup ids
WITH JSON '{"ticket_id":"T001","status":"resolved","note":"Policy evidence supports waiver."}';

PREVIEW WRITE 'last_proposal';               -- shell alias for newest returned wrp:// handle
APPROVE WRITE 'last_proposal' REASON 'reviewed evidence';
COMMIT WRITE 'last_proposal';

Approve policy-matched proposals

sql

-- This step is for Synapsor-native tables. Existing Postgres/MySQL proposals
-- are approved for trusted writeback instead of merged into the source DB.
CREATE SETTLEMENT POLICY support.green_ticket_settle -- inspects structured PAYLOAD, not prose
FOR CAPABILITY support.propose_ticket_resolution
TARGET BRANCH main
AUTO APPROVE WHEN
  PAYLOAD decision = 'approved'
  AND PAYLOAD reason_codes CONTAINS 'synapsor_auto_approval_gate'
  AND PAYLOAD risk_lane = 'green'
AUTO COMMIT
AUTO MERGE
ELSE LEAVE PROPOSED;

SETTLE WRITE 'last_proposal' USING POLICY support.green_ticket_settle; -- use returned wrp:// handle in app code

You're done.

Next: build out a full example agent or wire Synapsor into your app.