Documentation

Docs

What DataSnack does

Your business makes some decisions over and over: approve this refund or not, which team gets this ticket, does this ad match the offer. DataSnack makes those decisions for you, and gets faster and more consistent the more it makes them.

An everyday example

A shop gets refund requests all day. At first, an AI reads each one and decides by the shop's policy. After a few hundred, DataSnack notices that "delivered more than 30 days ago and not damaged" always means no. It writes that down as a rule, checks it against every past request, and from then on answers those by itself, instantly. Unusual requests still go to the AI.

Why you would want it

  • The same answer every time for the same request.
  • Instant: a rule answers in under a millisecond; AI takes seconds.
  • Cheaper: you don't pay for AI on answers a rule gives.
  • You can see why: every answer says which rule or AI made it, and the reason.

How you use it

  1. Name the decision you want to hand over.
  2. Have your system or AI agent send DataSnack each request with the answer it gave.
  3. Watch it learn: rules appear and are tested against your answers by themselves.
  4. Switch rules on when you are ready; anything they don't cover goes back to your system.

What you stay in control of

You can correct any answer, and corrections always win. Rules are tried silently before they answer anything, and you can turn any rule, or all of them, off in one click.

Quick start

  1. Sign in; a workspace is made for you.
  2. Create a gate: give your decision a name, and it learns from your system's answers. Or start from a template, and DataSnack's AI decides by its policy from day one.
  3. Create an API key under API keys. It is shown once.
  4. Send each request with your system's answer to observe (or, for a gate the AI answers, to decide). Rules are drafted, tested, run in shadow and promoted; switch the gate to act and they answer first.

Building in n8n? Use the DataSnack node.

n8n

Put a gate where your workflow used to wait for a person. The DataSnack node decides each request: tested rules answer on its Decided output, and what no rule covers comes out of Needs a person, where you wire the approval step you already use (Slack, Gmail or Teams "Send and wait"). The person's answer goes back to the gate with Record a person's answer, and the gate learns from it.

Install it (self-hosted n8n)

In the machine or container n8n runs in, install the package into n8n's nodes folder and restart n8n:

# Docker: docker exec -it n8n sh   (then the same)
mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install https://datasnack.ai/assets/n8n-nodes-datasnack-0.1.0.tgz
# then restart n8n

Search for DataSnack in the nodes panel. Create a DataSnack API credential with an API key from API keys. The node is not yet in n8n's verified community nodes, so on n8n Cloud use the example workflow below instead.

Use it

  1. Decide: choose the gate and map each input field from your data (or send JSON). Fields, types and allowed values come from the gate.
  2. Decided carries output, reason and decided_by; branch on output.decision with a Switch node.
  3. Needs a person: send the request to your approval step. Then add a DataSnack node with Record a person's answer; its Decision ID is the decision_id from Decide, and you map the person's answer to the gate's answer fields.
  4. Set the gate to send unmatched requests to a person (below), so in act mode every automatic answer comes from a tested rule.

Each Decide sends an idempotency key made from the execution, node and item, so n8n's Retry On Fail never decides twice. Set your own key (an order ID) under Options to be safe across executions too. For a gate that learns from your own system, the node's Observe sends a request with the answer your system gave.

n8n Cloud, or without the node

The example workflow does the same with n8n's own HTTP Request and If nodes: import it (Workflows → Import from file), create a Header Auth credential named Authorization with the value Bearer dsk_..., set your gate's slug in the two HTTP nodes, and replace "Ask a person" with your approval step.

Learning from your system

A gate can learn from the answers your own system already gives, with nothing to set up but a name. Its fields and answers are learned from what you send.

curl -X POST https://datasnack.ai/v1/gates \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Refund review", "observed": true}'

curl -X POST https://datasnack.ai/v1/gates/refund-review/observe \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"amount_usd": 42.5, "days_since_delivery": 41, "item_damaged": false}, "output": {"decision": "reject"}}'
{"decision_id": "d_06gyt…", "recorded": true,
 "learned": "Learned 4 new field(s) or value(s): [input.amount_usd input.days_since_delivery input.item_damaged output.decision]."}

Fields are widened as new ones appear: a new field or value is added, a whole number that turns out to have decimals becomes a number. After 50 answers, rules are drafted from them and tested against them, and they run in shadow as more answers arrive. Once they have proven themselves, switch the gate to act. Then call decide first: a rule or the cache answers, or the response has "tier": "none" and your system decides, and you send that answer to observe so the gate keeps learning. Choose a default answer instead in the gate's settings if you prefer. While a gate acts its fields are fixed, and its rules are checked against the answers you keep sending.

Deciding

One request, one decision. Send the gate's input as input; unknown fields and wrong types are refused.

curl -X POST https://datasnack.ai/v1/gates/refund-approval/decide \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"amount_usd": 42.5, "days_since_delivery": 41, "customer_tier": "plus", "item_damaged": false}}'
{
  "decision_id": "d_06cjbk3w8yq7ft0e2g9h1v5r4m",
  "output": {"decision": "reject", "category": "late"},
  "reason": "Delivered 41 days ago; the window is 30.",
  "decided_by": {"tier": "rule", "rule": "outside-window", "version": 1},
  "ms": 0
}

decided_by.tier says what answered: rule (a live rule, named with its version), cache (an identical input answered before under the same config), model (the AI model, against your policy), or default (your failure policy, when the model could not answer, or the default answer when no rule applies), or none (no rule applies and the gate leaves the decision to a person: output is empty; see below). The response has the same shape whichever answered.

Fetch a decision later with GET /v1/decisions/{id}.

Corrections

When a decision was wrong, send the right answer. A correction becomes the decision's truth: rules are judged against it first, and a rule that disagrees with a correction is never promoted.

curl -X POST https://datasnack.ai/v1/decisions/$DECISION_ID/feedback \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output": {"decision": "approve", "category": "damaged"}, "note": "Arrived broken", "who": "ana@example.com"}'

Gates and configs

A gate is one decision with a typed input, a closed typed output and a policy in words. Its config is versioned; each save is a new version. Configs are YAML in the dashboard and JSON in the API.

curl https://datasnack.ai/v1/gates -H "Authorization: Bearer $DATASNACK_KEY"

curl -X POST https://datasnack.ai/v1/gates \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "ticket-triage"}'

curl "https://datasnack.ai/v1/gates/ticket-triage/config?format=yaml" -H "Authorization: Bearer $DATASNACK_KEY"

PUT /v1/gates/{slug}/config takes the same bodies as creating one: a config as JSON, {"yaml": "..."} or {"template": "..."}. A save is refused if a live or shadow rule no longer fits the new config.

Field types: string, number, integer, boolean, enum (with values) and list of strings. Outputs are closed: enum, boolean, integer or number, and exactly one has decides: true. Every response also has a reason.

Rules

A rule is a condition in CEL over input.<field> and params.<name>, and the literal output it gives. Rules run in priority order, lower first; the first whose condition holds answers. A rule that reads a field the request left out abstains.

curl -X POST https://datasnack.ai/v1/gates/refund-approval/rules \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "outside-window", "priority": 10,
       "when": "input.days_since_delivery > params.window_days && !input.item_damaged",
       "then": {"decision": "reject", "category": "late"},
       "reason": "Delivered {input.days_since_delivery} days ago; the window is {params.window_days}."}'

Rules you write start in shadow. Rules DataSnack drafts start as proposed, and move to shadow when their test report passes. Each report has four parts, kept apart: history (every logged decision, where corrections must all agree), synthetic (inputs made around the condition and judged by the model three times: agreement with the model, not proof), invariants (the same answer twice, an output that fits, bad inputs refused) and exhaustive (every combination, when the rule reads only booleans and enums).

curl https://datasnack.ai/v1/gates/refund-approval/rules -H "Authorization: Bearer $DATASNACK_KEY"

curl -X POST https://datasnack.ai/v1/gates/refund-approval/rules/outside-window/1/status \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "live"}'

Modes and promotion

observe
The model answers every request. No rule runs.
shadow
The model answers; rules run silently beside it and are compared with its answers.
act
Live rules and the cache answer first; what they do not cover goes to the model, a person or the default answer, by the gate's unmatched setting.
curl -X POST https://datasnack.ai/v1/gates/refund-approval/mode \
  -H "Authorization: Bearer $DATASNACK_KEY" -H "Content-Type: application/json" -d '{"mode": "act"}'

curl -X POST https://datasnack.ai/v1/gates/refund-approval/rollback -H "Authorization: Bearer $DATASNACK_KEY"

A rule in shadow is ready when it has matched promotion.min_shadow requests, no person's correction disagrees with it, and the bound on its error rate, (disagreements + 3) ÷ matches, is at most promotion.max_error. With promotion.auto it then goes live by itself and you are told; otherwise you are told and promote it. A share of live rule answers (audit_rate) is checked by the model afterwards; when the audited disagreement over the last 200 goes over max_error, the rule is demoted to shadow automatically. Rolling back a gate sets it to observe.

When no rule applies

In act mode, a request no live rule covers is answered by the gate's unmatched setting (in the dashboard: Learning and safety settings → When no rule applies in act mode):

model
The AI answers by your policy (the default).
person
No answer: the response has "tier": "none" and an empty output, and a person decides. Send their answer to POST /v1/decisions/{id}/feedback: the same request is answered with it from then on, and rules are drafted from it.
default
The gate's failure.default_output, with tier default.
unmatched: person   # in the gate's YAML config

With person or default the AI never answers in act mode (it only re-checks a share of rule answers, as audits), so every automatic answer comes from a tested rule, or repeats an answer a person gave to the identical request. In observe and shadow modes the AI still answers, since that is how rules earn promotion.

MCP

Every gate in a workspace is a tool on one MCP server, at https://datasnack.ai/mcp (streamable HTTP), with the workspace's API key as the bearer. A gate refund-approval is the tool decide_refund_approval; its input schema is the gate's input, and its result is the decide response.

{
  "mcpServers": {
    "datasnack": {
      "url": "https://datasnack.ai/mcp",
      "headers": {"Authorization": "Bearer $DATASNACK_KEY"}
    }
  }
}

Retries

Send an Idempotency-Key header with decide or observe and a retry is safe: the same key with the same request gets the first answer back (with Idempotent-Replayed: true), and no second decision is made, logged, charged to the model or counted against the daily limit. Keys are per workspace, up to 255 printable characters, and kept a day. Use one key per request: an order or ticket ID works.

curl -X POST https://datasnack.ai/v1/gates/refund-approval/decide \
  -H "Authorization: Bearer $DATASNACK_KEY" \
  -H "Idempotency-Key: refund-order-1001" \
  -H "Content-Type: application/json" \
  -d '{"input": {"amount_usd": 42.5, "days_since_delivery": 41}}'

A key reused for a different request is refused (422), and a retry while the first is still being decided gets 409: retry a moment later. A request that fails keeps no key, so its retry runs again. If DataSnack's database is briefly unreachable, requests are still answered, without the guarantee.

Timeouts and failures

Rule and cache decisions are served from memory and keep answering if our database or the model provider is down. A model decision takes a few seconds and is bounded by a deadline; when the model fails, the gate's failure policy answers (default returns default_output with tier default) or returns an error (502). Give your client a timeout and decide what to do without an answer.

// Node
const res = await fetch(url, {method: "POST", headers, body: JSON.stringify({input}),
  signal: AbortSignal.timeout(25000)}).catch(() => null);
const decision = res && res.ok ? await res.json() : {output: {decision: "ask"}, reason: "No answer in time."};
# Python
try:
    r = requests.post(url, headers=headers, json={"input": input}, timeout=25)
    r.raise_for_status()
    decision = r.json()
except requests.RequestException:
    decision = {"output": {"decision": "ask"}, "reason": "No answer in time."}

Errors

401
No API key, or a revoked one.
404
No such gate or decision in this workspace.
409
A slug already taken, a config changed since you read it, observe on a gate the AI answers, or a request with the same Idempotency-Key still under way.
422
The input, config or rule does not fit (problems lists each issue), or an Idempotency-Key reused for a different request.
429
The workspace used today's decisions.
502
The model failed and the gate's policy is to return an error.