---
name: xanoscript-builder
category: API
description: >
  Definitive guide for writing native XanoScript that works on the first deploy. Covers endpoint creation, function building, db.query WHERE syntax, precondition error_types, filters, api.request, security methods, variable patterns, control flow, and the incremental build-test-deploy workflow. Built from production experience -- every gotcha is runtime-verified.
---

# XanoScript Builder

Write native XanoScript that works on the first deploy. Every concept uses **closed sets** (exhaustive valid values) so you never guess.

**Rule: If it's not documented here as valid, it doesn't exist.**

**Workflow:** Write raw XanoScript using this guide → Deploy to Xano → Curl test → Iterate.

---

## Layer 1: Mental Model

XanoScript is a **constrained DSL**, not a programming language. Three rules:

1. **Closed sets everywhere** - Every block, keyword, and parameter has a finite list of valid values
2. **No freestyle** - Ternary operators, complex expressions, and dynamic constructs fail silently or throw cryptic errors
3. **Context-specific** - What works inside `db.query` is different from what works inside `var`

**Consequence:** Never assume syntax from JavaScript/Python will work. Always check the closed set first.

---

## Layer 2: Containers (endpoint / function / task)

### Endpoint
```xanoscript
query "path/name" verb=POST {
  api_group = "Group Name"        // optional
  auth = "users"                  // optional - table name for JWT auth (use EXACT table name including emoji prefix if any!)

  input {
    text email filters=trim|to_lower
    text password
    int page?=1                   // ? = optional, ?=1 = default
  }

  stack {
    // All logic goes here
  }

  response = { success: true }    // or response = $variable
  tags = ["tag1", "tag2"]         // optional
}
```

**Endpoint valid blocks:** `api_group`, `auth`, `input`, `stack`, `response`, `tags` - NOTHING ELSE.
**Valid verbs:** `GET`, `POST`, `PATCH`, `PUT`, `DELETE` - NOTHING ELSE.
**`input {}` is REQUIRED** even if empty - omitting it throws "Missing input block" at deploy.

### Function
```xanoscript
function "Folder/function_name" {
  input {
    int user_id
    text message?
  }

  stack {
    // Logic here
  }

  response = { success: true, data: $result }
}
```

**Function valid blocks:** `input`, `stack`, `response` - NOTHING ELSE.

### Task (Background Job)
```xanoscript
task "task_name" {
  stack {
    // No input, no response - runs on schedule
  }
}
```

**Task valid blocks:** `stack` - NOTHING ELSE. Tasks have NO input and NO response.

---

## Layer 3: Inputs & Variables

### Input Types
```xanoscript
input {
  text name filters=trim           // required text
  int amount                       // required integer
  bool active?                     // optional boolean (? suffix)
  text status?=pending             // optional with default (NO SPACES in defaults!)
  email user_email filters=trim    // email type with filter
  json metadata?                   // optional JSON
  decimal price?                   // optional decimal
}
```

**Valid input types:** `text`, `int`, `bool`, `email`, `password`, `decimal`, `json`, `timestamp`, `date`, `enum`, `uuid`, `file`, `image`, `video`, `audio` - see [closed-sets.md](resources/closed-sets.md).

### Variables
```xanoscript
var $name { value = "expression" }       // Declare
var.update $name { value = "new_value" } // Update (NEVER re-declare!)
```

**Special variables (no $ prefix):** `now` (current timestamp)
**Special variables ($ prefix):** `$auth.id` (after auth), `$input.*`, `$db.table.field` (in WHERE), `$env.KEY`

**`$env.KEY` behavior:** Missing env vars return `null` (no error thrown). See loose equality below.

**System env vars NOT available in raw XanoScript (runtime-verified):**
`$remote_ip`, `$http_headers`, `$request_method`, `$request_uri`, `$request_querystring`, `$datasource`, `$branch` exist in Xano's visual builder dropdown but are NOT accessible in raw XanoScript via any tested mechanism (`$remote_ip`, `$env.remote_ip`, `util.get_env`). These are visual-builder-only features.

### Loose Equality (runtime-verified)

XanoScript has loose equality: `null == ""`, `null == 0`, `null == false`, `0 == false`, `false == ""`, `[] == null` are ALL `true`. Only `0 == ""` is `false`.

**Consequence:** `$env.MISSING_KEY` returns null, and `null == ""` is true. You cannot distinguish missing from empty with `==`.

```xanoscript
// WRONG: Re-declare to update
var $count { value = $count + 1 }

// RIGHT: Use var.update
var.update $count { value = $count + 1 }
```

---

## Layer 4: Database Operations

**This is where most mistakes happen. Read carefully.**

**CRITICAL RULE: ALWAYS verify table names and field names in the Xano dashboard (or via API) BEFORE writing any database operation. Wrong names deploy fine but fail at runtime with cryptic errors.**

### db.query - The Valid Blocks

db.query accepts **7 valid blocks**: `where`, `sort`, `return`, `output`, `join`, `eval`, `addon`. Nothing else.

```xanoscript
// WRONG - "Invalid block: filters"
db.query users { filters = {status: "active"} }

// WRONG - "Invalid block: paging"
db.query users { paging = {page: 1, per_page: 10} }

// RIGHT - valid blocks only
db.query users {
  where = $db.users.status == "active"
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: 1, per_page: 20, totals: true}}
} as $users

// WITH JOIN + EVAL
db.query orders {
  join = {
    c: {
      table: "customers"
      where: $db.orders.customer_id == $db.c.id
    }
  }
  where = $db.orders.customer_id != 0
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: 1, per_page: 20}}
  eval = {
    customer_name: $db.c.name
  }
  output = ["items.id", "items.total", "items.customer_name"]
} as $result
```

**Join rules:** `join` connects tables, `eval` pulls joined fields into response. Without `eval`, joined data doesn't appear. Join alias (e.g. `c`) is referenced as `$db.c.field`. See [database-operations.md](resources/database-operations.md).

**Addon rules:** Addons enrich each row with related data from pre-defined reusable queries. Use `$output.field` for per-row field references (NOT `$db.` or quoted strings).
```xanoscript
db.query products {
  return = {type: "list", paging: {page: 1, per_page: 10}}
  addon = [{
    name: "Category Info"
    input: {category_id: $output.category_id}
    as: "items.category"
  }]
  output = ["items.id", "items.name", "items.category"]
} as $result
```
See [database-operations.md](resources/database-operations.md).

**`totals: true` in paging:** Without it, `$result.itemsTotal` and `$result.pageTotal` DON'T EXIST. You only get `itemsReceived`, `curPage`, `nextPage`, `prevPage`, `offset`, `perPage`. Add `totals: true` when you need total count. See [database-operations.md](resources/database-operations.md).

### WHERE Syntax - The Closed Set

```xanoscript
// VALID operators: ==  !=  >  <  >=  <=  &&  ||  ~(contains)
where = $db.table.field == "value"
where = $db.table.field != null
where = $db.table.status == "active" && $db.table.role == "admin"
where = $db.table.role == "admin" || $db.table.role == "mod"

// WRONG - No ternary in WHERE
where = ($input.status != null) ? ($db.table.status == $input.status) : true

// RIGHT - Use conditional branches for optional filters
conditional {
  if ($input.status != null) {
    db.query items { where = $db.items.status == $input.status ... } as $items
  } else {
    db.query items { ... } as $items  // no where clause
  }
}
```

### return + paging - The ONLY Valid Syntax

```xanoscript
return = {type: "list"}                                    // all records
return = {type: "list", paging: {page: 1, per_page: 20}}  // paginated (no totals)
return = {type: "list", paging: {page: 1, per_page: 20, totals: true}} // with totals
return = {type: "count"}                                   // count only (returns integer)
return = {type: "single"}                                  // first matching record (object)
return = {type: "exists"}                                  // boolean true/false
```

**paging is INSIDE return, never standalone. sort direction MUST be quoted.**
**`{type: "first"}` is INVALID - use `{type: "single"}` instead.**

### CRUD Quick Reference

```xanoscript
db.get "table" { field_name = "id", field_value = $id } as $record
db.add "table" { data = { field: $value } } as $new
db.edit "table" { field_name = "id", field_value = $id, data = { field: $value } } as $updated
db.del "table" { field_name = "id", field_value = $id }   // db.del NOT db.delete!
```

**Both db.add and db.edit use `data =` (NOT `content =`!)**

### db.edit - data MUST Be Inline (runtime-verified)
```xanoscript
// WRONG - "Invalid kind for data - assign:var"
var $update { value = {}|set:"name":$input.name }
db.edit "items" { field_value = $id, data = $update }

// RIGHT - Inline data object with variable references
db.edit "items" { field_value = $id, data = { name: $input.name, updated_at: now } }
```

See [database-operations.md](resources/database-operations.md) for full reference.

---

## Layer 5: Precondition & Validation

```xanoscript
precondition ($user != null) {
  error_type = "notfound"
  error = "User not found"
}
```

### error_type - The Closed Set (EXACTLY 7 values, runtime-verified 2026-02-20)

| error_type | HTTP Code | Response Code | Use For |
|---|---|---|---|
| `"standard"` | 500 | `ERROR_FATAL` | Generic errors (same as omitting error_type) |
| `"inputerror"` | 400 | `ERROR_CODE_INPUT_ERROR` | Input validation failures |
| `"badrequest"` | 400 | `ERROR_CODE_BAD_REQUEST` | Malformed requests |
| `"unauthorized"` | 401 | `ERROR_CODE_UNAUTHORIZED` | Authentication failures (bad/missing token) |
| `"accessdenied"` | 403 | `ERROR_CODE_ACCESS_DENIED` | Permission/ownership failures |
| `"notfound"` | 404 | `ERROR_CODE_NOT_FOUND` | Record doesn't exist |
| `"toomanyrequests"` | 429 | `ERROR_CODE_TOO_MANY_REQUESTS` | Rate limiting |

**CRITICAL:** Values are validated at RUNTIME, not deploy time. Bad values deploy fine but explode on first request.
**ANY other string (like "invalid", "error", "not_found", "field_error") throws a runtime validation error.**

```xanoscript
// WRONG - "invalid" is NOT a valid error_type (common mistake!)
precondition ($input.name != "") { error_type = "invalid", error = "Name required" }

// WRONG - "not_found" has no underscore
precondition ($item != null) { error_type = "not_found", error = "Not found" }

// RIGHT - use "inputerror" for validation
precondition ($input.name != "") { error_type = "inputerror", error = "Name required" }

// RIGHT - simplified (defaults to standard/500)
precondition ($input.name != "") { error = "Name required" }
```

**Security best practice:** Use same generic error for user-not-found AND wrong-password:
```xanoscript
precondition ($user != null) { error_type = "accessdenied", error = "Invalid Credentials." }
precondition ($pass_result)  { error_type = "accessdenied", error = "Invalid Credentials." }
```

---

## Layer 6: Control Flow

**CRITICAL:** `elseif` and `else` MUST be on their OWN LINE after the closing `}`. Parentheses work for all conditions. No backticks needed.

```xanoscript
// CONDITIONAL with else/elseif - OWN LINE, PARENTHESES (runtime-verified)
conditional {
  if ($status == "active") {
    // logic
  }
  elseif ($status == "pending") {
    // logic
  }
  else {
    // default
  }
}

// WRONG - elseif on SAME LINE as } → "Syntax error: unexpected '{'"
// conditional { if (...) { } elseif (...) { } }

// SWITCH/CASE - BROKEN at runtime (deploys fine but NEVER matches cases!)
// Always use conditional if/elseif instead. See what-doesnt-work.md #24c.

// FOR LOOP - count-based iteration, 0-indexed (runtime-verified)
for (5) {
  each as $i {
    var.update $results { value = $results|push:$i }   // $i = 0, 1, 2, 3, 4
  }
}

// WHILE LOOP - condition-based iteration (runtime-verified)
while ($counter < 10) {
  each {                        // "each" block required, NO alias
    var.update $counter { value = $counter|add:1 }
  }
}

// BREAK and CONTINUE - work inside for/while/foreach (runtime-verified)
for (10) {
  each as $i {
    conditional {
      if ($i == 5) { break }       // Exit loop entirely
      if ($i == 3) { continue }    // Skip this iteration
    }
  }
}

// FOREACH - NEVER use "item" as alias (shadows internal variable!)
foreach ($users) {
  each as $row {                // Use $row, $record, $entry - NOT $item
    var $name { value = $row.name }
  }
}

// TRY/CATCH - DOES NOT WORK in raw XanoScript ("unexpected 'try'")
// Use null-as-success pattern instead:
var $result { value = null }
// ... do risky operation, check result ...
conditional {
  if ($result == null) { var.update $result { value = {}|set:"success":true } }
}

// IF-ONLY (no else) - parentheses OK here
conditional {
  if ($input.name != "") { var.update $count { value = $count|add:1 } }
}
```

### foreach Property Access WORKS, |map BROKEN (runtime-verified)

```xanoscript
// RIGHT - $row.field access works fine in foreach
var $ids { value = [] }
foreach ($query_result.items) {
  each as $row { var.update $ids { value = $ids|push:$row.id } }
}

// WRONG - |map:"field" BROKEN → "id is not defined" at runtime
var $ids { value = $query_result.items|map:"id" }
```

---

## Layer 7: Filters

Filters transform values. Chain with `|`: `$value|filter1:param|filter2:param`

### Filter Results in Conditionals - MUST Store First

```xanoscript
// WRONG - "Invalid filter name: count == 0" (parser reads "count == 0" as one filter)
conditional { if ($arr|count == 0) { } }

// RIGHT - Store filter result in variable, then compare
var $arr_len { value = $arr|count }
conditional { if ($arr_len == 0) { } }
```

### Key Filters (Correct Names)

| Need | Filter | WRONG name |
|------|--------|------------|
| To string | `\|to_text` | ~~\|to_string~~ |
| To lowercase | `\|to_lower` | ~~\|lowercase~~ |
| To uppercase | `\|to_upper` | |
| Trim whitespace | `\|trim` | |
| Replace | `\|replace:"old":"new"` | |
| Count items | `\|count` | ~~\|length~~ |
| First item | `\|first` | |
| Push to array | `\|push:$val` | |
| Concatenate | `\|concat:$str` | ~~+ operator~~ |
| Set property | `\|set:"key":$val` | |
| Get property | `\|get:"key":default` | |
| Index by field | `\|index_by:"field"` | ~~\|group_by~~ (note: values are arrays) |
| Add number | `\|add:N` | |
| Round | `\|round:2` | |
| Time math | `\|add_secs_to_timestamp:86400` | ~~now + 86400~~ |
| Format time | `\|format_timestamp:"Y-m-d"` | ~~\|transform_timestamp~~ (returns "0"!) |
| SHA256 | `\|sha256` | |
| JSON encode | `\|json_encode` | |
| Extract field | ~~\|map:"field"~~ | **BROKEN** - use foreach + \|push |

### Filters That DON'T Work (Top Mistakes)

These look like they should work but **FAIL in XanoScript**:

| Wrong | Error | Use Instead |
|---|---|---|
| `\|map:"field"` | "field is not defined" at runtime | foreach + `\|push:$row.field` |
| `\|filter:'expr'` | "$item is not defined" | foreach + conditional |
| `\|reduce:'expr':0` | "$item is not defined" | foreach with accumulator |
| `\|to_string` | Invalid filter name | `\|to_text` |
| `\|length` | Invalid filter name | `\|count` (arrays), `\|strlen` (strings) |
| `\|group_by:"f"` | Does not exist | `\|index_by:"f"` (values are arrays!) |
| `\|default:val` | Does not exist | conditional fallback |
| `\|contains:val` on arrays | Wrong result (string-only!) | foreach + conditional |
| `\|transform_timestamp` | Returns "0" | `\|format_timestamp` |
| `\|delete:"key"` | Invalid filter name | `\|unset:"key"` |
| `\|implode:sep` | Invalid filter name | `\|join:sep` |

See [filters-reference.md](resources/filters-reference.md) for complete verified list + all non-existent filters.

**Chain for performance (600% faster than multiple var.update):**
```xanoscript
var $obj { value = {}|set:"a":$x|set:"b":$y|set:"c":$z }
```

See [filters-reference.md](resources/filters-reference.md) for complete list.

---

## Layer 8: API Requests & Function Calls

### api.request
```xanoscript
var $auth_header { value = "Authorization: Bearer "|concat:$env.API_KEY }

api.request {
  url = "https://api.example.com/endpoint"
  method = "POST"                     // Can also be a variable: method = $input.http_method
  params = $request_body              // PARAMS not body!
  headers = []|push:$auth_header|push:"Content-Type: application/json"
  timeout = 120
} as $result

// Response is NESTED - check timeout FIRST
conditional {
  if ($result.response.result == false) {
    throw { name = "TIMEOUT" value = "API call timed out" }
  }
}
var $data { value = $result.response.result }
var $status { value = $result.response.status }
```

**Input defaults gotcha:** URLs and strings with special chars (`://`, `?`, `&`) CANNOT be used as input defaults (`text url?=https://...` causes error 524). Make such inputs required instead.

### function.run
```xanoscript
function.run "Folder/FunctionName" {
  input = {
    param1: $value1
    param2: "literal"
  }
} as $result
```

### Security Methods (Production-Verified Names)
```xanoscript
security.check_password {
  text_password = $input.password
  hash_password = $user.password
} as $pass_result

// CRITICAL: Uses `table =` NOT `auth =`. ALL 4 blocks REQUIRED.
security.create_auth_token {
  table = "🔐 [AUTH] users"   // Exact table name (including emoji if any!)
  id = $user.id
  extras = {}                  // Custom JWT claims: {}|set:"role":"admin"
  expiration = 604800          // seconds (604800 = 7 days)
} as $authToken
```

See [security-methods.md](resources/security-methods.md) for full auth patterns.

### Utility Functions (runtime-verified)
```xanoscript
// Get ALL user-defined env vars as one object (does NOT include system env vars)
util.get_env {} as $all_env
var $api_key { value = $all_env|get:"openai_secret":"" }

// Get ALL raw input including undeclared query params
util.get_input {} as $raw_input    // {test_param: "hello", foo: "bar"}

// Get only declared inputs (matching input {} block)
util.get_all_input {} as $declared  // {test_param: "hello"}

// Get all in-scope variables
util.get_vars {} as $all_vars

// Set response headers
util.set_header { name = "X-Custom", value = "test" }

// Pause execution (value in milliseconds)
util.sleep { value = 2000 }

// IP geolocation
util.ip_lookup { ip = "8.8.8.8" } as $geo

// Distance between coordinates
util.geo_distance { lat1 = 40.7, lon1 = -74.0, lat2 = 34.0, lon2 = -118.2 } as $dist
```

**`util.get_input` vs `util.get_all_input`:** `get_input` returns ALL query params/body data (even undeclared ones). `get_all_input` returns ONLY params matching the `input {}` block.

---

## Layer 9: Workflow

```
1. Write MINIMAL XanoScript (one operation)
2. Deploy to Xano
3. Curl test IMMEDIATELY
4. Add ONE feature
5. Redeploy (NEVER create duplicates — update the existing endpoint!)
6. Curl test again
7. REPEAT until complete
```

**NEVER build complete solution first. NEVER skip curl testing.**

See [workflow.md](resources/workflow.md) and [curl-testing.md](resources/curl-testing.md).

---

## Navigation Guide

| Need to... | Read this |
|---|---|
| Copy-paste complete patterns (CRUD, auth, AI, webhooks) | [recipes.md](resources/recipes.md) |
| Check ALL valid values for any field | [closed-sets.md](resources/closed-sets.md) |
| See what DOESN'T work | [what-doesnt-work.md](resources/what-doesnt-work.md) |
| Full database operation reference | [database-operations.md](resources/database-operations.md) |
| Auth, password, token patterns | [security-methods.md](resources/security-methods.md) |
| All filter names and gotchas | [filters-reference.md](resources/filters-reference.md) |
| Build-test-deploy process | [workflow.md](resources/workflow.md) |
| Curl testing patterns | [curl-testing.md](resources/curl-testing.md) |

---

**Status**: PRODUCTION-READY | **Design**: Closed-set architecture - never guess, always verify
**Source**: Runtime-verified from extensive stress testing across production workspaces

# Closed Sets - Every Valid Value for Every Field

**Rule:** If a value is not listed here, it will throw a validation error. Never guess.

---

## precondition error_type (EXACTLY 7, runtime-verified 2026-02-20)

| error_type | HTTP Code | Response Code | Use For |
|---|---|---|---|
| `"standard"` | 500 | `ERROR_FATAL` | Generic errors (same as omitting error_type) |
| `"inputerror"` | 400 | `ERROR_CODE_INPUT_ERROR` | Input validation failures |
| `"badrequest"` | 400 | `ERROR_CODE_BAD_REQUEST` | Malformed requests |
| `"unauthorized"` | 401 | `ERROR_CODE_UNAUTHORIZED` | Bad/missing auth token |
| `"accessdenied"` | 403 | `ERROR_CODE_ACCESS_DENIED` | Ownership/permission failure |
| `"notfound"` | 404 | `ERROR_CODE_NOT_FOUND` | Record not found |
| `"toomanyrequests"` | 429 | `ERROR_CODE_TOO_MANY_REQUESTS` | Rate limiting |

**CRITICAL:** Validated at RUNTIME not deploy time. Bad values deploy fine but explode on first request.
**Common WRONG values:** `"invalid"`, `"error"`, `"not_found"`, `"field_error"`, `"fatal"`, `"input_error"`

---

## Endpoint verb (EXACTLY 5)

`GET`, `POST`, `PATCH`, `PUT`, `DELETE`

---

## db.query valid blocks (EXACTLY 7)

| Block | Purpose | Required |
|---|---|---|
| `where` | Filter expression using `$db.table.field` syntax | No (omit for all records) |
| `sort` | Sort order `{field: "asc"\|"desc"}` | No |
| `return` | Result type + paging | No (defaults to list) |
| `output` | Field selection `["items.field1", "items.field2"]` | No (defaults to all) |
| `join` | Cross-table join `{alias: {table: "name", where: ...}}` | No |
| `eval` | Pull joined fields into response `{new_name: $db.alias.field}` | No (required to see join data) |
| `addon` | Enrich rows with reusable queries `[{name: "...", input: {...}, as: "items.field"}]` | No |

**Anything else throws:** `Invalid block: <name>`. Common failures: `filters`, `paging`, `filter`, `limit`, `search`, `addons` (use `addon` singular).

---

## db.query return type values (EXACTLY 4 valid types)

| Value | Returns |
|---|---|
| `{type: "list"}` | All matching records (array) |
| `{type: "list", paging: {page: N, per_page: N}}` | Paginated records. Add `totals: true` for `itemsTotal`/`pageTotal` |
| `{type: "count"}` | Integer count only |
| `{type: "single"}` | First matching record (object, not array) |
| `{type: "exists"}` | Boolean true/false |
| ~~`{type: "first"}`~~ | **INVALID** - use `{type: "single"}` or list + `|first` filter |
| ~~`{type: "stream"}`~~ | Deploys but returns "@stream" string marker, not data |
| ~~`{type: "aggregate"}`~~ | Requires separate aggregate block (syntax TBD) |

---

## db.query where operators (EXACTLY 8)

| Operator | Example |
|---|---|
| `==` | `$db.table.field == "value"` |
| `!=` | `$db.table.field != null` |
| `>` | `$db.table.age > 18` |
| `<` | `$db.table.price < 100` |
| `>=` | `$db.table.stock >= 1` |
| `<=` | `$db.table.rating <= 5` |
| `&&` | Combine with AND |
| `\|\|` | Combine with OR |
| `~` | Contains (string) |

**NOT valid in where:** Ternary (`? :`), function calls, `|filter`, `IN`, `LIKE`, `ILIKE`

---

## Input field types

| Type | XanoScript | Notes |
|---|---|---|
| `text` | `text name` | String |
| `int` | `int amount` | Integer |
| `bool` | `bool active` | Boolean |
| `decimal` | `decimal price` | Decimal number |
| `email` | `email user_email` | Email with validation |
| `password` | `password pass` | Hashed on storage |
| `timestamp` | `timestamp created_at` | Date/time |
| `date` | `date due_date` | Date only |
| `json` | `json metadata` | JSON object/array |
| `enum` | `enum status` | Enumerated values |
| `uuid` | `uuid id` | UUID string |
| `file` | `file attachment` | File upload |
| `image` | `image avatar` | Image upload |
| `video` | `video clip` | Video upload |
| `audio` | `audio recording` | Audio upload |

### Input modifiers

| Syntax | Meaning |
|---|---|
| `text name` | Required, not nullable |
| `text name?` | Optional, not nullable |
| `text name?=default` | Optional with default value |
| `text name filters=trim\|to_lower` | With filters (pipe-separated) |

---

## Endpoint container valid blocks (EXACTLY 6)

| Block | Required | Purpose |
|---|---|---|
| `input` | No | Parameter definitions |
| `stack` | Yes | Logic operations |
| `response` | Yes | Return value |
| `auth` | No | JWT auth table name |
| `api_group` | No | API group name |
| `tags` | No | Array of tags |

---

## Function container valid blocks (EXACTLY 3)

| Block | Required | Purpose |
|---|---|---|
| `input` | No | Parameter definitions |
| `stack` | Yes | Logic operations |
| `response` | Yes | Return value |

---

## Task container valid blocks (EXACTLY 1)

| Block | Required | Purpose |
|---|---|---|
| `stack` | Yes | Logic operations |

Tasks have NO input and NO response.

---

## db.get valid blocks

| Block | Required | Purpose |
|---|---|---|
| `field_name` | No | Field to match (default: "id") |
| `field_value` | Yes | Value to match |
| `output` | No | Fields to return |

---

## db.add valid blocks

| Block | Required | Purpose |
|---|---|---|
| `data` | Yes | Record data object |

**NOT `content`!** Using `content =` throws error.

---

## db.edit valid blocks

| Block | Required | Purpose |
|---|---|---|
| `field_name` | No | Field to match (default: "id") |
| `field_value` | Yes | Value to match |
| `data` | Yes | Fields to update |

---

## db.del valid blocks

| Block | Required | Purpose |
|---|---|---|
| `field_name` | No | Field to match (default: "id") |
| `field_value` | Yes | Value to match |

**Note:** Command is `db.del` NOT `db.delete`.

---

## sort direction values (EXACTLY 2)

`"asc"`, `"desc"` - **MUST be quoted strings.**

```xanoscript
sort = {created_at: "desc"}   // RIGHT
sort = {created_at: desc}     // WRONG - unquoted
```

---

## Special Variables

| Variable | When Available | Notes |
|---|---|---|
| `now` | Always | Current timestamp, NO $ prefix |
| `$auth.id` | After `auth = "table"` | Authenticated user ID |
| `$input.*` | After input block | Input parameters |
| `$db.table.field` | Inside `where` clause | Database field reference |
| `$env.KEY` | Always | Environment variable |
| `$record` | In triggers | The triggering record |

---

## Time constants (seconds)

| Duration | Seconds |
|---|---|
| 1 minute | 60 |
| 1 hour | 3600 |
| 1 day | 86400 |
| 1 week | 604800 |
| 30 days | 2592000 |
| 1 year | 31536000 |

Use with: `now|add_secs_to_timestamp:86400` (NOT `now + 86400`)

---

## Conditional syntax (runtime-verified 2026-02-21)

| Construct | Condition Syntax | Notes |
|---|---|---|
| `if` only | Parentheses: `if ($x == 1)` | Works fine |
| `if` + `else` | Parentheses: `if ($x == 1)` | `else {` on OWN LINE after `}` |
| `if` + `elseif` + `else` | Parentheses: `if ($x == 1)` | Each keyword on own line |
| `switch/case` | **BROKEN** | Deploys but never matches cases — always hits default |

**CRITICAL:** `elseif` and `else` MUST start on their OWN LINE after `}`. Same-line → "Syntax error: unexpected '{'"
**Backticks are NOT needed** — parentheses work for all conditions (verified 2026-02-21).
**switch/case is broken at runtime** — always use conditional if/elseif instead.

---

## db.edit data block

| Syntax | Works? |
|---|---|
| `data = { field: $var, field2: $var2 }` | YES - inline object |
| `data = $variable` | **NO** - "Invalid kind for data - assign:var" |

Must use inline object. Build individual field variables, then reference in inline data.

---

## Loose Equality Truth Table (runtime-verified 2026-02-20)

XanoScript uses **loose equality** with `==`. These comparisons are ALL `true`:

| Expression | Result | Surprise? |
|---|---|---|
| `null == ""` | `true` | Yes - can't distinguish null from empty string |
| `null == 0` | `true` | Yes - null equals zero |
| `null == false` | `true` | Yes - null equals false |
| `0 == false` | `true` | Expected |
| `false == ""` | `true` | Yes |
| `[] == null` | `true` | Yes - empty array equals null! |
| `0 == ""` | `false` | Only exception in the null/empty/false/zero family |

**Consequence:** `$env.MISSING_KEY` returns `null`. Since `null == ""` is true, you cannot use `== ""` to check for missing env vars. There is currently no way to distinguish a missing env var from one set to empty string.

# Curl Testing Reference

Curl patterns that work for testing XanoScript endpoints.

---

## Critical Rule: Multi-Line JSON Format

**Always use multi-line JSON to avoid shell escaping issues.**

```bash
# WORKS - Multi-line format
curl -X POST https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Item",
    "status": "active"
  }'

# FAILS - Compact format causes shell escaping issues
curl -s -X POST "url" -d '{"name":"Test Item","status":"active"}'
```

---

## Common Patterns

### POST - Create

```bash
curl -X POST https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Item",
    "status": "active"
  }'
```

### GET - Read (No Body)

```bash
curl -X GET "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items/123"
```

### GET - With Query Parameters

```bash
curl -X GET "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items?page=1&per_page=10&status=active"
```

### PATCH - Update

```bash
curl -X PATCH https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items/123 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name"
  }'
```

### DELETE

```bash
curl -X DELETE "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items/123"
```

---

## Authenticated Endpoints

```bash
# Get token first
TOKEN=$(curl -s -X POST https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }' | jq -r '.authToken')

# Use token
curl -X GET "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/auth/me" \
  -H "Authorization: Bearer $TOKEN"

# Authenticated POST
curl -X POST https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "My Item"
  }'
```

---

## Reading Responses

### Pretty Print with jq

```bash
curl -s -X GET "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items" | jq .
```

### Extract Specific Fields

```bash
# Get just the items array
curl -s ... | jq '.items'

# Get count
curl -s ... | jq '.items | length'

# Get first item ID
curl -s ... | jq '.items[0].id'
```

### Check HTTP Status Code

```bash
curl -s -o /dev/null -w "%{http_code}" -X GET "url"
```

---

## Testing Error Cases

### Missing Required Field

```bash
curl -X POST https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items \
  -H "Content-Type: application/json" \
  -d '{}'
# Should return 400 with error message
```

### Invalid Auth

```bash
curl -X GET "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/auth/me" \
  -H "Authorization: Bearer invalid_token"
# Should return 401
```

### Not Found

```bash
curl -X GET "https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/items/99999"
# Should return 404 if precondition is set up
```

---

## URL Structure

```
https://{instance}.n7c.xano.io/api:{api_group_slug}/{endpoint_path}
```

- **instance**: Your Xano instance (e.g., `abc1-d2e3-fg4h`)
- **api_group_slug**: The API group's URL slug (e.g., `xNXqMlqb`)
- **endpoint_path**: The endpoint path (e.g., `items`, `auth/login`)

The api_group_slug is returned when you create the API group or can be found in the Xano dashboard.

---

## Test After Every Deploy

```bash
# 1. Deploy
# (use create_endpoint or update_endpoint via MCP)

# 2. Test immediately
curl -X POST https://YOUR-INSTANCE.n7c.xano.io/api:GROUP/endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "test": "value"
  }'

# 3. Read the ACTUAL response
# Don't assume - read what comes back

# 4. If error, check error message against what-doesnt-work.md
# 5. Fix and update_endpoint
# 6. Test again
```

---

## Common Curl Mistakes

| Mistake | Fix |
|---|---|
| Missing Content-Type header | Add `-H "Content-Type: application/json"` |
| Single-line JSON with quotes | Use multi-line format |
| GET with body | Use query parameters instead |
| Wrong HTTP method | Match endpoint verb (GET/POST/PATCH/DELETE) |
| Missing Bearer prefix | Use `"Authorization: Bearer $TOKEN"` not just the token |
| URL not quoted | Wrap URL in quotes if it has special chars |

# Database Operations Reference

Complete reference for all db.* operations with correct syntax.

---

## Table of Contents
- [CRUD Operations](#crud-operations)
- [Query Operations](#query-operations)
- [Bulk Operations](#bulk-operations)
- [Advanced Operations](#advanced-operations)
- [Transactions](#transactions)
- [Common Patterns](#common-patterns)

---

## CRUD Operations

### db.get - Get Single Record

```xanoscript
// By ID (default)
db.get "users" { field_value = $input.user_id } as $user

// By specific field
db.get "users" {
  field_name = "email"
  field_value = $input.email
} as $user

// With field selection
db.get "users" {
  field_value = $input.user_id
  output = ["id", "name", "email"]
} as $user
```

**Valid blocks:** `field_name` (optional, default "id"), `field_value` (required), `output` (optional)

### db.add - Create Record

```xanoscript
// CRITICAL: Uses `data =` NOT `content =`
db.add "users" {
  data = {
    name: $input.name
    email: $input.email
    created_at: now
  }
} as $new_user
```

**Valid blocks:** `data` (required)

### db.edit - Update Record

```xanoscript
// CRITICAL: Uses `data =` NOT `content =`
db.edit "users" {
  field_name = "id"
  field_value = $input.user_id
  data = {
    name: $input.name
    updated_at: now
  }
} as $updated_user
```

**Valid blocks:** `field_name` (optional, default "id"), `field_value` (required), `data` (required)

### db.del - Delete Record

```xanoscript
// CRITICAL: Command is db.del NOT db.delete
db.del "posts" {
  field_name = "id"
  field_value = $input.post_id
}
```

**Valid blocks:** `field_name` (optional, default "id"), `field_value` (required)

---

## Query Operations

### db.query - The Most Important Operation

**Valid blocks: `where`, `sort`, `return`, `output`, `join`, `eval`, `addon`. NOTHING ELSE.**

```xanoscript
db.query users {
  where = $db.users.status == "active"
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: 1, per_page: 20}}
  output = ["items.*", "itemsTotal", "itemsReceived", "curPage", "nextPage"]
} as $users
```

### WHERE Syntax

WHERE uses `$db.table.field` expression notation. NOT JSON objects.

```xanoscript
// Simple equality
where = $db.users.status == "active"

// Multiple conditions (AND)
where = $db.users.status == "active" && $db.users.role == "admin"

// OR conditions
where = $db.users.role == "admin" || $db.users.role == "mod"

// Comparisons
where = $db.orders.total > 100
where = $db.products.stock >= 1
where = $db.reviews.rating <= 5

// Null check
where = $db.posts.deleted_at == null
where = $db.users.verified_at != null

// Against variables
where = $db.posts.user_id == $auth.id
where = $db.items.status == $input.status

// Contains (string search, case-sensitive)
where = $db.posts.title ~ "keyword"

// Case-insensitive search
where = ($db.posts.title|to_lower) ~ ($input.search|to_lower)
```

**Valid WHERE operators:** `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `~`
**NOT valid in WHERE:** Ternary (`? :`), function calls, `IN`, `LIKE`, `ILIKE`

### return + paging Syntax

```xanoscript
// All records
return = {type: "list"}

// Paginated (WITHOUT total count - faster, default)
return = {type: "list", paging: {page: $input.page, per_page: 20}}

// Paginated WITH total count (adds itemsTotal + pageTotal to response)
return = {type: "list", paging: {page: $input.page, per_page: 20, totals: true}}

// Count only
return = {type: "count"}

// Single record (runtime-verified 2026-02-20)
return = {type: "single"}

// Existence check (runtime-verified 2026-02-20)
return = {type: "exists"}

// INVALID return types:
// return = {type: "first"}  ← INVALID! Use {type: "single"} instead
```

**paging is INSIDE return. Never standalone.**

**CRITICAL: `totals: true` in paging (runtime-verified 2026-02-20)**

By default, Xano skips calculating total count for performance. Without `totals: true`, you get:
`itemsReceived`, `curPage`, `nextPage`, `prevPage`, `offset`, `perPage`

With `totals: true`, you ALSO get: **`itemsTotal`** and **`pageTotal`**

```xanoscript
// WRONG - "Unable to locate var: result.itemsTotal"
db.query users {
  return = {type: "list", paging: {page: 1, per_page: 20}}
} as $result
var $total { value = $result.itemsTotal }  // FAILS - field doesn't exist!

// RIGHT - Add totals: true to get itemsTotal
db.query users {
  return = {type: "list", paging: {page: 1, per_page: 20, totals: true}}
} as $result
var $total { value = $result.itemsTotal }  // Works! Returns 252
var $pages { value = $result.pageTotal }   // Works! Returns 13
```

### sort Syntax

```xanoscript
// Single field - direction MUST be quoted
sort = {created_at: "desc"}

// Multiple fields
sort = {pinned: "desc", created_at: "desc"}
```

### output Syntax

```xanoscript
// All item fields plus pagination info (requires totals: true for itemsTotal!)
output = ["items.*", "itemsTotal", "itemsReceived", "curPage", "nextPage"]

// Specific item fields only
output = ["items.id", "items.name", "items.email"]

// IDs only (for |map pattern)
output = ["items.id"]
```

**Note:** Including `"itemsTotal"` in output does nothing if `totals: true` is not in paging. The field is silently dropped.

### Accessing Query Results

**Always available (no totals needed):**
```xanoscript
db.query users { return = {type: "list", paging: {page: 1, per_page: 20}} } as $result

var $items { value = $result.items }
var $received { value = $result.itemsReceived }  // items in THIS page
var $page { value = $result.curPage }
var $next { value = $result.nextPage }
var $prev { value = $result.prevPage }
var $offset { value = $result.offset }
var $per_page { value = $result.perPage }
```

**Only available with `totals: true`:**
```xanoscript
db.query users {
  return = {type: "list", paging: {page: 1, per_page: 20, totals: true}}
} as $result

var $total { value = $result.itemsTotal }   // total matching records across ALL pages
var $pages { value = $result.pageTotal }    // total number of pages
```

### Optional WHERE (Dynamic Filtering)

You CANNOT use ternary in WHERE. Use conditional branches instead.

```xanoscript
// For optional status filter
conditional {
  if ($input.status != null) {
    db.query items {
      where = $db.items.status == $input.status
      sort = {created_at: "desc"}
      return = {type: "list", paging: {page: $input.page, per_page: 20}}
    } as $items
  } else {
    db.query items {
      sort = {created_at: "desc"}
      return = {type: "list", paging: {page: $input.page, per_page: 20}}
    } as $items
  }
}
```

### db.count - DOES NOT EXIST as Standalone (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "unexpected 'db.count'" - this command doesn't exist!
db.count users { where = $db.users.status == "active" } as $count

// RIGHT - Use db.query with return type "count"
db.query users {
  where = $db.users.status == "active"
  return = {type: "count"}
} as $count   // returns integer directly
```

### db.has - Check Existence (runtime-verified 2026-02-21)

**CRITICAL: db.has uses `field_value` syntax (like db.get), NOT `where` syntax (like db.query)!**

```xanoscript
// WRONG - "Missing block2: field_value"
db.has users { where = $db.users.email == $input.email } as $exists

// RIGHT - Uses field_value syntax
db.has "users" {
  field_name = "email"
  field_value = $input.email
} as $exists  // returns true/false

// RIGHT - Default field_name is "id"
db.has "users" { field_value = 123 } as $exists

// For complex existence checks, use db.query with return type "exists"
db.query users {
  where = $db.users.status == "active" && $db.users.role == "admin"
  return = {type: "exists"}
} as $exists  // returns true/false
```

**Valid blocks:** `field_name` (optional, default "id"), `field_value` (required)

---

## Bulk Operations - DO NOT EXIST (runtime-verified 2026-02-21)

**CRITICAL:** `db.bulkAdd`, `db.bulkUpdate`, and `db.bulkDelete` do NOT exist in raw XanoScript. They throw "unexpected 'db.bulkAdd'" etc. at deploy time.

```xanoscript
// WRONG - None of these exist!
db.bulkAdd "users" { data = $records }           // "unexpected 'db.bulkAdd'"
db.bulkUpdate "orders" { filters = {...} }        // "unexpected 'db.bulkUpdate'"
db.bulkDelete "logs" { filters = {...} }          // "unexpected 'db.bulkDelete'"

// RIGHT - Use foreach for bulk operations
var $records { value = []|push:{name: "User 1"}|push:{name: "User 2"} }
foreach ($records) {
  each as $row {
    db.add "users" { data = { name: $row.name } }
  }
}

// RIGHT - For bulk delete, query then loop
db.query logs {
  where = $db.logs.created_at < $cutoff
  return = {type: "list"}
} as $old_logs
foreach ($old_logs.items) {
  each as $row {
    db.del "logs" { field_value = $row.id }
  }
}
```

---

## Advanced Operations

### db.addOrEdit - DOES NOT EXIST (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "unexpected 'db.addOrEdit'" - this command doesn't exist!
db.addOrEdit "settings" {
  field_name = "user_id"
  field_value = $auth.id
  data = { theme: $input.theme }
} as $settings

// RIGHT - Use db.has + conditional + db.add/db.edit
db.has "settings" {
  field_name = "user_id"
  field_value = $auth.id
} as $exists

conditional {
  if ($exists) {
    db.edit "settings" {
      field_name = "user_id"
      field_value = $auth.id
      data = { theme: $input.theme, updated_at: now }
    } as $settings
  }
  else {
    db.add "settings" {
      data = { user_id: $auth.id, theme: $input.theme, updated_at: now }
    } as $settings
  }
}
```

### db.patch - Partial Update

```xanoscript
db.patch "users" {
  field_value = $user_id
  data = { last_login: now }
}
```

### db.set_datasource

```xanoscript
// ALWAYS first in stack, ALWAYS hardcoded
db.set_datasource { value = "live" }
// Or: db.set_datasource { value = "test" }
```

---

## Transactions

```xanoscript
db.transaction {
  stack {
    db.edit "accounts" {
      field_value = $from_id
      data = { balance: $from_balance|subtract:$amount }
    }
    db.edit "accounts" {
      field_value = $to_id
      data = { balance: $to_balance|add:$amount }
    }
    db.add "transfers" {
      data = { from: $from_id, to: $to_id, amount: $amount, created_at: now }
    }
  }
}
```

All operations inside `stack` are atomic - if any fail, all roll back.

---

## Joins + Eval (runtime-verified 2026-02-20)

**CRITICAL: Always confirm table names and field names with `list_tables` and `get_table_schema` BEFORE writing any join/eval. Joins deploy fine but fail at runtime with cryptic errors ("missing bind parameter - dbo") if the table name or field name is wrong.**

Joins connect related tables for filtering/sorting. Use `eval` to pull fields from joined tables into your response.

```xanoscript
// Join syntax: alias → { table, where }
// Eval syntax: new_field_name: $db.alias.field
db.query action_items {
  join = {
    kt: {
      table: "krisp_transcripts"
      where: $db.action_items.transcript_id == $db.kt.id
    }
  }
  where = $db.action_items.transcript_id != 0
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: 1, per_page: 20}}
  eval = {
    meeting_title: $db.kt.meeting_title
    meeting_type: $db.kt.meeting_type
  }
  output = ["items.id", "items.action_text", "items.meeting_title", "items.meeting_type"]
} as $result
```

**Key rules:**
- `join` is an object: `{ alias: { table: "actual_table_name", where: condition } }`
- The alias (e.g. `kt`) is what you reference in `eval` and `where` as `$db.kt.field`
- `eval` creates computed fields from joined data - without it, joined fields DON'T appear in response
- `output` selects which fields to include (use `items.field_name` for eval fields too)
- Multiple joins supported: add more keys to the join object

**Common errors:**
- `"missing bind parameter - dbo"` → Table name is wrong. Use `list_tables` to verify.
- `"Unsupported parameter reference - xdo.field"` → Field name is wrong. Use `get_table_schema` to verify.

### Addons - Reusable Query Enrichment (runtime-verified 2026-02-20)

**CRITICAL: Addons must be pre-defined in the workspace before referencing. Use `list_addons` to see available addons.**

Addons enrich each row with related data from other tables using pre-defined reusable queries. They solve the N+1 problem efficiently.

```xanoscript
db.query "💬 [CHAT] companions" {
  where = $db.CHAT_companions.is_active == true
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: 1, per_page: 10}}
  addon = [{
    name: "Lora Model"
    input: {lora_models_id: $output.lora_model_id}
    as: "items.lora_info"
  }]
  output = ["items.id", "items.name", "items.lora_model_id", "items.lora_info"]
} as $result
```

**Key rules:**
- `addon` is an array of objects: `[{ name, input, as }]`
- `name` must match an existing addon name exactly (use `list_addons` to check)
- `input` maps addon parameters to per-row field values using **`$output.field_name`** (NOT `$db.`, NOT quoted strings)
- `as` specifies where enriched data appears: `"items.your_key"` for list results
- Multiple addons supported: add more objects to the array
- Empty addons (no matching data) return `null` for that row

**Input field reference syntax:**
- `$output.lora_model_id` → per-row field value (WORKS)
- `"$output.lora_model_id"` → literal string, addon returns null (WRONG)
- `"lora_model_id"` → literal string, addon returns null (WRONG)
- `$db.table.field` → syntax error "Unknown kind for static object: assign:db" (WRONG)
- `388` → hardcoded value, same for every row (works but not dynamic)

### Alternative: Sequential Queries

When joins are overkill or you need full control:
```xanoscript
db.query action_items {
  return = {type: "list", paging: {page: 1, per_page: 5}}
} as $items

var $enriched { value = [] }
foreach ($items.items) {
  each as $row {
    db.get "krisp_transcripts" { field_value = $row.transcript_id } as $t
    var.update $enriched { value = $enriched|push:({}|set:"item":$row|set:"transcript":$t) }
  }
}
```

---

## Common Patterns

### Find or 404

```xanoscript
db.get "users" { field_value = $input.id } as $user
precondition ($user != null) {
  error_type = "notfound"
  error = "User not found"
}
```

### Check Unique Before Create

```xanoscript
db.has users {
  where = $db.users.email == $input.email
} as $exists

precondition (!$exists) {
  error_type = "inputerror"
  error = "Email already registered"
}

db.add "users" { data = { email: $input.email } } as $user
```

### Ownership Check

```xanoscript
db.get "posts" { field_value = $input.post_id } as $post
precondition ($post != null) {
  error_type = "notfound"
  error = "Post not found"
}
precondition ($post.user_id == $auth.id) {
  error_type = "accessdenied"
  error = "Not authorized"
}
```

### Paginated List with Defaults

```xanoscript
var $page { value = $input.page }
conditional {
  if ($page == null) { var.update $page { value = 1 } }
}

db.query products {
  where = $db.products.active == true
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: $page, per_page: 20, totals: true}}
} as $result

response = {
  items: $result.items
  total: $result.itemsTotal
  pages: $result.pageTotal
  page: $result.curPage
}
```

**Note:** `totals: true` is required here to get `itemsTotal` and `pageTotal`. Without it, those fields don't exist in the response.

### Soft Delete

```xanoscript
db.edit "posts" {
  field_value = $input.id
  data = { deleted_at: now, deleted_by: $auth.id }
}

// Query excluding soft-deleted
db.query posts {
  where = $db.posts.deleted_at == null
  return = {type: "list"}
} as $active_posts
```

### Increment Counter

```xanoscript
db.get "posts" { field_value = $input.post_id } as $post
db.edit "posts" {
  field_value = $input.post_id
  data = { view_count: $post.view_count|add:1 }
}
```

---

## Quick Reference

| Operation | Syntax | Key Block |
|---|---|---|
| Get one | `db.get "table" { field_value = $id }` | `field_value` |
| Create | `db.add "table" { data = {...} }` | `data` (NOT content!) |
| Update | `db.edit "table" { field_value = $id, data = {...} }` | `data` |
| Delete | `db.del "table" { field_value = $id }` | `field_value` |
| Query | `db.query table { where, sort, return, output, join, eval, addon }` | 7 valid blocks |
| Count | `db.query table { where = ..., return = {type: "count"} }` | Returns integer (db.count doesn't exist!) |
| Exists | `db.has "table" { field_name = "f", field_value = $v }` | Returns boolean (uses field_value, NOT where!) |
| Exists (complex) | `db.query table { where = ..., return = {type: "exists"} }` | Returns boolean |
| ~~Upsert~~ | ~~db.addOrEdit~~ | **DOESN'T EXIST** - use db.has + conditional |
| ~~Bulk Add~~ | ~~db.bulkAdd~~ | **DOESN'T EXIST** - use foreach + db.add |
| ~~Bulk Update~~ | ~~db.bulkUpdate~~ | **DOESN'T EXIST** - use foreach + db.edit |
| ~~Bulk Delete~~ | ~~db.bulkDelete~~ | **DOESN'T EXIST** - use foreach + db.del |

# Filters Reference (Runtime-Verified 2026-02-20)

Complete reference for XanoScript filters. Chain with `|`: `$value|filter1:param|filter2:param`

**CRITICAL:** Many filters listed in SDK documentation **DO NOT WORK** in raw XanoScript. Only filters marked **VERIFIED** have been tested at runtime. SDK-only filters deploy fine but fail when called.

---

## Table of Contents
- [String Filters (Verified)](#string-filters-verified)
- [Number Filters (Verified)](#number-filters-verified)
- [Array Filters (Verified)](#array-filters-verified)
- [Object Filters (Verified)](#object-filters-verified)
- [Type Conversion (Verified)](#type-conversion-verified)
- [Time Filters (Verified)](#time-filters-verified)
- [Hash and Crypto (Verified)](#hash-and-crypto-verified)
- [Encoding (Verified)](#encoding-verified)
- [SDK-Only Filters (DO NOT USE in raw XanoScript)](#sdk-only-filters)
- [Common Wrong Names](#common-wrong-names)

---

## String Filters (Verified)

All tested at runtime 2026-02-20.

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|to_lower` | Lowercase | `$s\|to_lower` | VERIFIED |
| `\|to_upper` | Uppercase | `$s\|to_upper` | VERIFIED |
| `\|capitalize` | First letter upper | `$s\|capitalize` | VERIFIED |
| `\|trim` | Remove whitespace | `$s\|trim` | VERIFIED |
| `\|ltrim` | Trim left | `$s\|ltrim` | Deployed OK |
| `\|rtrim` | Trim right | `$s\|rtrim` | Deployed OK |
| `\|strlen` | String length | `$s\|strlen` | VERIFIED |
| `\|substr:start:len` | Substring | `$s\|substr:0:10` | VERIFIED |
| `\|replace:old:new` | Replace text | `$s\|replace:"x":"y"` | VERIFIED |
| `\|contains:str` | Contains check (string only!) | `$s\|contains:"keyword"` | VERIFIED |
| `\|starts_with:str` | Starts with | `$s\|starts_with:"http"` | VERIFIED |
| `\|ends_with:str` | Ends with | `$s\|ends_with:".com"` | VERIFIED |
| `\|concat:str` | Concatenate | `$s\|concat:" world"` | VERIFIED |
| `\|join:sep` | Join array to string | `$arr\|join:", "` | VERIFIED |
| `\|url_encode` | URL encode | `$s\|url_encode` | VERIFIED |
| `\|escape_html` | HTML escape | `$s\|escape_html` | Deployed OK |
| `\|nl2br` | Newlines to `<br>` | `$s\|nl2br` | Deployed OK |
| `\|regex_replace:p:r` | Regex replace | `$s\|regex_replace:"/\\d/":"X"` | Deployed OK |
| `\|regex_extract:p` | Regex extract first | `$s\|regex_extract:"/\\d+/"` | Deployed OK |

### String Filters That DO NOT EXIST in Raw XanoScript

| Filter | Error | Use Instead |
|---|---|---|
| ~~`\|explode:sep`~~ | "Invalid filter name: explode" | No raw equivalent - use API or hardcode |
| ~~`\|implode:sep`~~ | "Invalid filter name: implode" | Use `\|join:sep` instead |
| ~~`\|pad_left:len:char`~~ | "Invalid filter name: pad_left" | No raw equivalent |
| ~~`\|pad_right:len:char`~~ | "Invalid filter name: pad_right" | No raw equivalent |
| ~~`\|snake_case`~~ | "Invalid filter name: snake_case" | No raw equivalent |
| ~~`\|camel_case`~~ | "Invalid filter name: camel_case" | No raw equivalent |
| ~~`\|word_count`~~ | "Invalid filter name: word_count" | No raw equivalent |
| ~~`\|number_format`~~ | Not tested | Use `\|round` + `\|to_text` |

---

## Number Filters (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|add:n` | Addition | `$x\|add:5` | VERIFIED |
| `\|subtract:n` | Subtraction | `$x\|subtract:3` | Deployed OK |
| `\|multiply:n` | Multiplication | `$x\|multiply:2` | Deployed OK |
| `\|divide:n` | Division | `$x\|divide:4` | Deployed OK |
| `\|round:d` | Round to decimals | `$x\|round:2` | VERIFIED |
| `\|floor` | Round down | `$x\|floor` | Deployed OK |
| `\|ceil` | Round up | `$x\|ceil` | Deployed OK |
| `\|abs` | Absolute value | `$x\|abs` | Deployed OK |

---

## Array Filters (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|count` | Array length | `$arr\|count` | VERIFIED |
| `\|first` | First element | `$arr\|first` | VERIFIED |
| `\|last` | Last element | `$arr\|last` | VERIFIED |
| `\|push:item` | Add to end | `$arr\|push:$val` | VERIFIED |
| `\|unshift:item` | Add to start | `$arr\|unshift:$val` | Deployed OK |
| `\|pop` | Remove last | `$arr\|pop` | Deployed OK |
| `\|shift` | Remove first | `$arr\|shift` | Deployed OK |
| `\|slice:start:length` | Extract portion (start + length!) | `$arr\|slice:2:3` | VERIFIED |
| `\|reverse` | Reverse order | `$arr\|reverse` | VERIFIED |
| `\|unique` | Remove duplicates | `$arr\|unique` | VERIFIED |
| `\|flatten` | Flatten nested | `$arr\|flatten` | VERIFIED |
| `\|shuffle` | Randomize order | `$arr\|shuffle` | VERIFIED |
| `\|sort` | Sort ascending | `$arr\|sort` | VERIFIED |
| ~~`\|sort_by:field`~~ | ~~Sort by field~~ | ~~`$arr\|sort_by:"name"`~~ | **SDK-ONLY** (see below) |
| `\|index_by:field` | Object keyed by field | `$arr\|index_by:"id"` | VERIFIED |
| `\|merge:arr` | Combine arrays | `$arr\|merge:$other` | VERIFIED |
| `\|diff:arr` | Items in first not second | `$a\|diff:$b` | VERIFIED |
| `\|intersect:arr` | Items in both | `$a\|intersect:$b` | VERIFIED |
| `\|remove:val` | Remove by value | `$arr\|remove:$val` | VERIFIED |
| `\|filter_empty` | Remove null/empty | `$arr\|filter_empty` | VERIFIED |
| `\|min` | Minimum value | `$arr\|min` | VERIFIED |
| `\|max` | Maximum value | `$arr\|max` | VERIFIED |

### Array Filters That DO NOT EXIST in Raw XanoScript

| Filter | Error | Use Instead |
|---|---|---|
| ~~`\|at:n`~~ | "Invalid filter name: at" | Use `\|slice:n:1\|first` |
| ~~`\|index_of:val`~~ | "Invalid filter name: index_of" | Use foreach to find |
| ~~`\|map:"field"`~~ | "field is not defined" at runtime | foreach + `\|push:$row.field` |

**Note:** `\|slice` uses `start:length` NOT `start:end`. `$arr\|slice:2:3` returns 3 items starting at index 2.

---

## Object Filters (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|set:key:val` | Set property | `$obj\|set:"name":"John"` | VERIFIED |
| `\|get:key:default` | Get with default | `$obj\|get:"key":"fallback"` | VERIFIED |
| `\|has:key` | Has property? | `$obj\|has:"email"` | VERIFIED |
| `\|unset:key` | Remove property | `$obj\|unset:"password"` | VERIFIED |
| `\|merge:obj` | Combine objects | `$obj\|merge:$other` | VERIFIED |
| `\|keys` | Get all keys | `$obj\|keys` | VERIFIED |
| `\|values` | Get all values | `$obj\|values` | VERIFIED |
| `\|entries` | Key-value pairs [{key,value}] | `$obj\|entries` | VERIFIED |
| `\|pick:field` | Keep FIRST field only (multi-key broken!) | `$obj\|pick:"name"` | VERIFIED (caveat!) |
| `\|unpick:fields` | Remove fields | `$obj\|unpick:["password"]` | Deployed OK |

**CAVEAT: `|pick` only picks the FIRST key!** Multi-key `|pick:"a":"c"` silently returns only `{a: 1}`, ignoring "c". For multiple keys, build a new object: `{}|set:"a":($obj|get:"a":null)|set:"c":($obj|get:"c":null)`. Use `|unpick` to remove keys instead (works correctly).

### Object Filters That DO NOT EXIST in Raw XanoScript

| Filter | Error | Use Instead |
|---|---|---|
| ~~`\|delete:key`~~ | "Invalid filter name: delete" | Use `\|unset:"key"` |

**Performance tip:** Chain `|set` in one expression instead of multiple `var.update`:
```xanoscript
// 600% faster
var $obj { value = {}|set:"a":$x|set:"b":$y|set:"c":$z }
```

---

## Type Conversion (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|to_text` | Convert to string | `$num\|to_text` | VERIFIED |
| `\|to_int` | Convert to integer | `$str\|to_int` | Deployed OK |
| `\|to_decimal` | Convert to float | `$str\|to_decimal` | Deployed OK |
| `\|to_bool` | Convert to boolean | `$str\|to_bool` | Deployed OK |
| `\|json_encode` | Object to JSON string | `$obj\|json_encode` | VERIFIED |
| `\|json_decode` | JSON string to object | `$str\|json_decode` | Deployed OK |
| `\|safe_array` | Ensure value is array | `$val\|safe_array` | Deployed OK |

---

## Time Filters (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|add_secs_to_timestamp:n` | Add/subtract seconds | `now\|add_secs_to_timestamp:86400` | VERIFIED |
| `\|format_timestamp:fmt` | Format timestamp | `now\|format_timestamp:"Y-m-d"` | VERIFIED |
| `\|parse_timestamp` | Parse date string | `"2025-01-15"\|parse_timestamp` | Deployed OK |

### Time Filters That DON'T WORK Correctly

| Filter | Issue | Use Instead |
|---|---|---|
| ~~`\|transform_timestamp:fmt`~~ | Returns "0" instead of formatted date | Use `\|format_timestamp:fmt` |

**CRITICAL:** No direct arithmetic on timestamps!
```xanoscript
// WRONG
var $tomorrow { value = now + 86400 }
// RIGHT
var $tomorrow { value = now|add_secs_to_timestamp:86400 }
```

**Format codes:** Y=year, m=month(01-12), d=day(01-31), H=hour(00-23), i=minutes, s=seconds

---

## Hash and Crypto (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|sha256` | SHA-256 hash | `$data\|sha256` | VERIFIED |
| `\|md5` | MD5 hash | `$data\|md5` | Deployed OK |
| `\|sha1` | SHA-1 hash | `$data\|sha1` | Deployed OK |
| `\|sha512` | SHA-512 hash | `$data\|sha512` | Deployed OK |
| `\|hmac_sha256:secret` | HMAC-SHA256 | `$data\|hmac_sha256:$key` | Deployed OK |
| `\|hmac_sha1:secret` | HMAC-SHA1 | `$data\|hmac_sha1:$key` | Deployed OK |

---

## Encoding (Verified)

| Filter | Description | Example | Status |
|---|---|---|---|
| `\|base64_encode` | Base64 encode | `$data\|base64_encode` | VERIFIED |
| `\|base64_decode` | Base64 decode | `$data\|base64_decode` | Deployed OK |
| `\|url_encode` | URL encode | `$s\|url_encode` | VERIFIED |
| `\|url_decode` | URL decode | `$s\|url_decode` | Deployed OK |

---

## SDK-Only Filters (DO NOT USE in Raw XanoScript)

These filters exist in Xano's internal registry but **FAIL** when used in raw XanoScript (via `create_endpoint` / `update_endpoint`). They either throw "Invalid filter name" at deploy time or produce wrong results at runtime.

### Deploy-Time Failures (Invalid filter name)

| Filter | Use Instead |
|---|---|
| `\|sort_by:"field"` | Use `db.query sort` or foreach (runtime-verified 2026-02-21) |
| `\|explode:sep` | No raw equivalent for string split |
| `\|implode:sep` | Use `\|join:sep` |
| `\|at:n` | Use `\|slice:n:1\|first` |
| `\|index_of:val` | Use foreach to find |
| `\|pad_left:len:char` | No raw equivalent |
| `\|pad_right:len:char` | No raw equivalent |
| `\|snake_case` | No raw equivalent |
| `\|camel_case` | No raw equivalent |
| `\|pascal_case` | No raw equivalent |
| `\|kebab_case` | No raw equivalent |
| `\|word_count` | No raw equivalent |
| `\|delete:key` | Use `\|unset:"key"` |
| `\|is_numeric` | No raw equivalent (use conditional) |
| `\|is_empty` | Use `== null \|\| == ""` in conditional |
| `\|is_null` | Use `== null` in conditional |
| `\|is_array` | No raw equivalent |
| `\|is_email` | No raw equivalent |
| `\|is_url` | No raw equivalent |

### Runtime Failures (Deploy fine, fail when called)

| Filter | Error | Use Instead |
|---|---|---|
| `\|map:"field"` | "field is not defined" | foreach + `\|push:$row.field` |
| `\|filter:'$item.x == y'` | "$item is not defined" | foreach + conditional |
| `\|reduce:'$acc + $item':0` | "$item is not defined" | foreach with accumulator |
| `\|first_notempty:$a:$b` | Syntax error | conditional fallback |
| `\|first_notnull:$a:$b` | Syntax error | conditional fallback |
| `\|transform_timestamp:fmt` | Returns "0" | Use `\|format_timestamp:fmt` |

### Workaround for |filter:
```xanoscript
var $filtered { value = [] }
foreach ($items) {
  each as $row {
    conditional {
      if ($row.status == "active") {
        var.update $filtered { value = $filtered|push:$row }
      }
    }
  }
}
```

### Workaround for |reduce (sum):
```xanoscript
var $total { value = 0 }
foreach ($items) {
  each as $row {
    var.update $total { value = $total|add:$row.amount }
  }
}
```

### Workaround for |map:"field":
```xanoscript
var $ids { value = [] }
foreach ($items) {
  each as $row {
    var.update $ids { value = $ids|push:$row.id }
  }
}
```

---

## Common Wrong Names

| Wrong Name | Correct Name |
|---|---|
| `\|to_string` | `\|to_text` |
| `\|toString` | `\|to_text` |
| `\|length` | `\|count` (arrays) or `\|strlen` (strings) |
| `\|lowercase` | `\|to_lower` |
| `\|uppercase` | `\|to_upper` |
| `\|default:val` | Use conditional fallback |
| `\|group_by:"field"` | `\|index_by:"field"` (values are arrays!) |
| `\|contains:val` (array) | foreach + conditional (string-only filter) |
| `\|index_of:val` | **Does not exist** - use foreach |
| `\|implode:sep` | Use `\|join:sep` |
| `\|delete:key` | Use `\|unset:"key"` |
| `\|transform_timestamp` | Use `\|format_timestamp` |
| `\|explode:sep` | **Does not exist in raw XanoScript** |

---

**Status**: Runtime-verified from stress testing 2026-02-20
**Method**: Deploy + curl test each filter individually
**VERIFIED** = Tested at runtime with curl, confirmed correct output
**Deployed OK** = Deployed without error (not runtime-tested yet)

# Recipes — Complete Copy-Paste Patterns

Ready-to-deploy XanoScript for common use cases. Every recipe follows the incremental workflow: deploy minimal → curl test → add features → update → test again.

---

## Recipe 1: Full CRUD REST API (5 Endpoints)

### Create Item

```xanoscript
query "items/create" verb=POST {
  api_group = "Items API"
  auth = "users"

  input {
    text name filters=trim
    text description?
    text status?=active
  }

  stack {
    precondition ($input.name != "") {
      error_type = "inputerror"
      error = "Name is required"
    }

    db.add "items" {
      data = {
        name: $input.name
        description: $input.description
        status: $input.status
        user_id: $auth.id
        created_at: now
      }
    } as $new_item
  }

  response = { success: true, item: $new_item }
}
```

### List Items (Paginated + Search)

```xanoscript
query "items" verb=GET {
  api_group = "Items API"
  auth = "users"

  input {
    int page?=1
    int per_page?=20
    text search?
  }

  stack {
    conditional {
      if ($input.search != null && $input.search != "") {
        db.query items {
          where = $db.items.user_id == $auth.id && ($db.items.name|to_lower) ~ ($input.search|to_lower)
          sort = {created_at: "desc"}
          return = {type: "list", paging: {page: $input.page, per_page: $input.per_page, totals: true}}
        } as $result
      }
      else {
        db.query items {
          where = $db.items.user_id == $auth.id
          sort = {created_at: "desc"}
          return = {type: "list", paging: {page: $input.page, per_page: $input.per_page, totals: true}}
        } as $result
      }
    }
  }

  response = $result
}
```

### Get Single Item

```xanoscript
query "items/{items_id}" verb=GET {
  api_group = "Items API"
  auth = "users"

  input {
    int items_id
  }

  stack {
    db.get "items" { field_value = $input.items_id } as $item

    precondition ($item != null) {
      error_type = "notfound"
      error = "Item not found"
    }

    precondition ($item.user_id == $auth.id) {
      error_type = "accessdenied"
      error = "Not authorized"
    }
  }

  response = $item
}
```

### Update Item

```xanoscript
query "items/{items_id}" verb=PATCH {
  api_group = "Items API"
  auth = "users"

  input {
    int items_id
    text name?
    text description?
    text status?
  }

  stack {
    db.get "items" { field_value = $input.items_id } as $existing

    precondition ($existing != null) {
      error_type = "notfound"
      error = "Item not found"
    }

    precondition ($existing.user_id == $auth.id) {
      error_type = "accessdenied"
      error = "Not authorized"
    }

    // Build update fields — use existing values as fallback
    var $f_name { value = $existing.name }
    var $f_desc { value = $existing.description }
    var $f_status { value = $existing.status }

    conditional {
      if ($input.name != null && $input.name != "") {
        var.update $f_name { value = $input.name }
      }
    }
    conditional {
      if ($input.description != null) {
        var.update $f_desc { value = $input.description }
      }
    }
    conditional {
      if ($input.status != null && $input.status != "") {
        var.update $f_status { value = $input.status }
      }
    }

    db.edit "items" {
      field_value = $input.items_id
      data = {
        name: $f_name
        description: $f_desc
        status: $f_status
        updated_at: now
      }
    } as $updated
  }

  response = { success: true, item: $updated }
}
```

### Delete Item

```xanoscript
query "items/{items_id}" verb=DELETE {
  api_group = "Items API"
  auth = "users"

  input {
    int items_id
  }

  stack {
    db.get "items" { field_value = $input.items_id } as $existing

    precondition ($existing != null) {
      error_type = "notfound"
      error = "Item not found"
    }

    precondition ($existing.user_id == $auth.id) {
      error_type = "accessdenied"
      error = "Not authorized"
    }

    db.del "items" { field_value = $input.items_id }
  }

  response = { success: true, message: "Item deleted" }
}
```

---

## Recipe 2: Auth System (Signup + Login + Me)

### Signup

```xanoscript
query "auth/signup" verb=POST {
  api_group = "Auth"

  input {
    text name filters=trim
    email email filters=trim|to_lower
    password password
  }

  stack {
    precondition ($input.name != "") {
      error_type = "inputerror"
      error = "Name is required"
    }

    // Check for existing user
    db.has "users" {
      field_name = "email"
      field_value = $input.email
    } as $exists

    precondition ($exists == false) {
      error_type = "inputerror"
      error = "Email already registered"
    }

    // Create user (password auto-hashed by Xano if field type = password)
    db.add "users" {
      data = {
        name: $input.name
        email: $input.email
        password: $input.password
        role: "user"
        created_at: now
      }
    } as $user

    // Generate auth token
    security.create_auth_token {
      table = "users"
      id = $user.id
      extras = {}
      expiration = 604800
    } as $authToken
  }

  response = {
    authToken: $authToken
    user: {
      id: $user.id
      name: $user.name
      email: $user.email
    }
  }
}
```

### Login

```xanoscript
query "auth/login" verb=POST {
  api_group = "Auth"

  input {
    text email filters=trim|to_lower
    text password
  }

  stack {
    db.get "users" {
      field_name = "email"
      field_value = $input.email
    } as $user

    // Same error for not-found AND wrong-password (prevents enumeration)
    precondition ($user != null) {
      error_type = "accessdenied"
      error = "Invalid credentials"
    }

    security.check_password {
      text_password = $input.password
      hash_password = $user.password
    } as $pass_ok

    precondition ($pass_ok) {
      error_type = "accessdenied"
      error = "Invalid credentials"
    }

    security.create_auth_token {
      table = "users"
      id = $user.id
      extras = {}
      expiration = 604800
    } as $authToken

    db.edit "users" {
      field_value = $user.id
      data = { last_login: now }
    }
  }

  response = {
    authToken: $authToken
    user: {
      id: $user.id
      name: $user.name
      email: $user.email
    }
  }
}
```

### Get Current User

```xanoscript
query "auth/me" verb=GET {
  api_group = "Auth"
  auth = "users"

  input {}

  stack {
    db.get "users" {
      field_value = $auth.id
      output = ["id", "name", "email", "role", "created_at"]
    } as $user

    precondition ($user != null) {
      error_type = "notfound"
      error = "User not found"
    }
  }

  response = $user
}
```

---

## Recipe 3: External API Integration (AI Call)

```xanoscript
query "ai/generate" verb=POST {
  api_group = "AI"
  auth = "users"

  input {
    text prompt filters=trim
    text model?
  }

  stack {
    precondition ($input.prompt != "") {
      error_type = "inputerror"
      error = "Prompt is required"
    }

    // Build model variable first (avoid slash interpretation issues)
    var $model_name { value = "google/gemini-2.5-flash" }
    conditional {
      if ($input.model != null && $input.model != "") {
        var.update $model_name { value = $input.model }
      }
    }

    // Build request body
    var $body { value = {}|set:"model":$model_name|set:"messages":[] }
    var $msg { value = {}|set:"role":"user"|set:"content":$input.prompt }
    var.update $body { value = $body|set:"messages":([]|push:$msg) }

    // Build auth header
    var $auth_header { value = "Authorization: Bearer "|concat:$env.OPENROUTER_API_KEY }

    api.request {
      url = "https://openrouter.ai/api/v1/chat/completions"
      method = "POST"
      params = $body
      headers = []|push:$auth_header|push:"Content-Type: application/json"
      timeout = 120
    } as $ai_result

    // Check for timeout or error
    conditional {
      if ($ai_result.response.result == false) {
        precondition (false) {
          error_type = "standard"
          error = "AI request failed or timed out"
        }
      }
    }

    var $content { value = $ai_result.response.result.choices|first }
    var $text { value = $content.message.content }
  }

  response = {
    success: true
    text: $text
    model: $model_name
    status: $ai_result.response.status
  }
}
```

---

## Recipe 4: Webhook Handler with Signature Verification

```xanoscript
query "webhooks/stripe" verb=POST {
  api_group = "Webhooks"

  input {
    json payload
  }

  stack {
    // Verify webhook signature
    var $raw_body { value = $input._raw_body }
    var $received_sig { value = $input._headers.stripe_signature }
    var $expected_sig { value = $raw_body|hmac_sha256:$env.STRIPE_WEBHOOK_SECRET }

    precondition ($received_sig == $expected_sig) {
      error_type = "unauthorized"
      error = "Invalid webhook signature"
    }

    // Extract event type
    var $event_type { value = $input.payload|get:"type":"unknown" }

    // Handle different event types
    conditional {
      if ($event_type == "checkout.session.completed") {
        var $session { value = $input.payload|get:"data":{}|get:"object":{} }
        var $customer_email { value = $session|get:"customer_email":"" }

        // Update user's subscription status
        db.get "users" { field_name = "email", field_value = $customer_email } as $user
        conditional {
          if ($user != null) {
            db.edit "users" {
              field_value = $user.id
              data = { plan: "pro", upgraded_at: now }
            }
          }
        }
      }
      elseif ($event_type == "customer.subscription.deleted") {
        var $sub { value = $input.payload|get:"data":{}|get:"object":{} }
        var $cust_id { value = $sub|get:"customer":"" }

        db.get "users" { field_name = "stripe_customer_id", field_value = $cust_id } as $user
        conditional {
          if ($user != null) {
            db.edit "users" {
              field_value = $user.id
              data = { plan: "free", downgraded_at: now }
            }
          }
        }
      }
    }

    // Log the webhook
    db.add "webhook_logs" {
      data = {
        source: "stripe"
        event_type: $event_type
        payload: $input.payload
        created_at: now
      }
    }
  }

  response = { received: true }
}
```

---

## Recipe 5: Background Task (Scheduled Cleanup)

```xanoscript
task "cleanup_old_sessions" {
  stack {
    // Calculate 30 days ago
    var $cutoff { value = now|add_secs_to_timestamp:-2592000 }

    // Find expired sessions
    db.query sessions {
      where = $db.sessions.last_active < $cutoff
      return = {type: "list", paging: {page: 1, per_page: 100}}
    } as $old_sessions

    // Delete each one
    foreach ($old_sessions.items) {
      each as $row {
        db.del "sessions" { field_value = $row.id }
      }
    }

    // Log cleanup result
    var $count { value = $old_sessions.itemsReceived }
    db.add "system_logs" {
      data = {
        action: "cleanup_sessions"
        records_deleted: $count
        run_at: now
      }
    }
  }
}
```

---

## Recipe 6: Upsert Pattern (Create or Update)

```xanoscript
// XanoScript has no db.addOrEdit — use db.has + conditional

db.has "settings" {
  field_name = "user_id"
  field_value = $auth.id
} as $settings_exist

conditional {
  if ($settings_exist) {
    db.get "settings" { field_name = "user_id", field_value = $auth.id } as $current
    db.edit "settings" {
      field_value = $current.id
      data = {
        theme: $input.theme
        language: $input.language
        updated_at: now
      }
    } as $result
  }
  else {
    db.add "settings" {
      data = {
        user_id: $auth.id
        theme: $input.theme
        language: $input.language
        created_at: now
      }
    } as $result
  }
}
```

---

## Recipe 7: Collecting IDs from Query Results

```xanoscript
// |map is BROKEN in raw XanoScript — use foreach + push

db.query orders {
  where = $db.orders.user_id == $auth.id && $db.orders.status == "pending"
  return = {type: "list"}
} as $orders

// Extract just the IDs
var $order_ids { value = [] }
foreach ($orders.items) {
  each as $row {
    var.update $order_ids { value = $order_ids|push:$row.id }
  }
}

// Now $order_ids = [1, 5, 12, 34, ...]
var $order_count { value = $order_ids|count }
```

---

## Recipe 8: Join Two Tables + Output Specific Fields

```xanoscript
db.query orders {
  join = {
    u: {
      table: "users"
      where: $db.orders.user_id == $db.u.id
    }
  }
  where = $db.orders.status == "pending"
  sort = {created_at: "desc"}
  return = {type: "list", paging: {page: 1, per_page: 50}}
  eval = {
    customer_name: $db.u.name
    customer_email: $db.u.email
  }
  output = ["items.id", "items.total", "items.status", "items.customer_name", "items.customer_email", "items.created_at"]
} as $orders
```

**Remember:** `join` connects tables, `eval` pulls joined fields into the response. Without `eval`, joined data won't appear. The alias `u` is referenced as `$db.u.field`.

---

## Recipe 9: Rate Limiting

```xanoscript
// Count recent requests from this user
var $window_start { value = now|add_secs_to_timestamp:-60 }

db.query api_requests {
  where = $db.api_requests.user_id == $auth.id && $db.api_requests.created_at > $window_start
  return = {type: "count"}
} as $recent_count

precondition ($recent_count < 60) {
  error_type = "toomanyrequests"
  error = "Rate limit exceeded. Max 60 requests per minute."
}

// Log this request
db.add "api_requests" {
  data = { user_id: $auth.id, endpoint: "generate", created_at: now }
}
```

---

## Recipe 10: Building Objects Efficiently

```xanoscript
// FAST: Chain |set in one expression (recommended)
var $obj { value = {}|set:"name":$input.name|set:"email":$input.email|set:"role":"user"|set:"active":true }

// SLOW: Multiple var.update calls (6x slower)
var $obj { value = {} }
var.update $obj { value = $obj|set:"name":$input.name }
var.update $obj { value = $obj|set:"email":$input.email }
var.update $obj { value = $obj|set:"role":"user" }

// Building arrays with objects
var $items { value = [] }
foreach ($query_result.items) {
  each as $row {
    var $entry { value = {}|set:"id":$row.id|set:"name":$row.name|set:"total":$row.amount }
    var.update $items { value = $items|push:$entry }
  }
}
```

---

**Status**: All recipes use production-verified XanoScript syntax only.
**Gotcha reminder**: Always `list_tables` and `get_table_schema` before writing any db operation — table and field names must be exact.

# Security Methods Reference

Authentication, password handling, token generation, and authorization patterns.

**IMPORTANT:** Method names in this file are production-verified. The existing xanoscript skill may show different names (`password.verify`, `auth.createToken`) - use the names documented here instead.

---

## Table of Contents
- [Authentication Declaration](#authentication-declaration)
- [Password Handling](#password-handling)
- [Token Generation](#token-generation)
- [Hashing and Signing](#hashing-and-signing)
- [Production Auth Patterns](#production-auth-patterns)

---

## Authentication Declaration

### auth Block (Endpoints Only)

```xanoscript
query "users/profile" verb=GET {
  auth = "users"    // Table name containing user records

  stack {
    // After auth declaration, $auth.id is available
    db.get "users" { field_value = $auth.id } as $user
  }

  response = $user
}
```

**Key points:**
- `auth = "table_name"` in endpoint container (not inside stack)
- After auth, `$auth.id` contains the authenticated user's ID
- Request fails with 401 if no valid Bearer token
- Functions and Tasks do NOT have auth blocks

---

## Password Handling

### security.check_password - Verify Password

**Production-verified name** (from Workspace 5, Endpoint 379):

```xanoscript
security.check_password {
  text_password = $input.password
  hash_password = $user.password
} as $pass_result
```

Returns boolean. Use in precondition:

```xanoscript
precondition ($pass_result) {
  error_type = "accessdenied"
  error = "Invalid Credentials."
}
```

**Parameters:**
- `text_password` - The plain text password to check
- `hash_password` - The stored hash to compare against

---

## Token Generation

### security.create_auth_token - Generate Auth Token

**Production-verified name** (from Workspace 5, Endpoint 379):

```xanoscript
security.create_auth_token {
  table = "users"
  extras = {}
  expiration = 604800    // seconds (604800 = 7 days)
  id = $user.id
} as $authToken
```

**Parameters:**
- `table` - The auth table name (must match `auth = "table"` in endpoints)
- `extras` - Additional claims to include in token (usually `{}`)
- `expiration` - Token lifetime in seconds
- `id` - The user ID to encode in the token

**Common expiration values:**
| Duration | Seconds |
|---|---|
| 1 hour | 3600 |
| 24 hours | 86400 |
| 7 days | 604800 |
| 30 days | 2592000 |

---

## Hashing and Signing

These are FILTERS, not methods. Use with `|` pipe syntax.

### SHA256

```xanoscript
var $hash { value = $data|sha256 }
```

### HMAC-SHA256 (Webhook Signatures)

```xanoscript
var $signature { value = $payload|hmac_sha256:$env.WEBHOOK_SECRET }
```

### MD5

```xanoscript
var $hash { value = $data|md5 }
```

### Base64

```xanoscript
var $encoded { value = $data|base64_encode }
var $decoded { value = $encoded|base64_decode }
```

### UUID Generation

```xanoscript
var $unique_id { value = ""|uuid }
```

---

## Production Auth Patterns

### Login Endpoint (Complete)

```xanoscript
query "auth/login" verb=POST {
  api_group = "Auth"

  input {
    text email filters=trim|to_lower
    text password
  }

  stack {
    // Find user by email
    db.get "users" {
      field_name = "email"
      field_value = $input.email
    } as $user

    // Security: Same error for not-found AND wrong-password
    precondition ($user != null) {
      error_type = "accessdenied"
      error = "Invalid Credentials."
    }

    // Verify password
    security.check_password {
      text_password = $input.password
      hash_password = $user.password
    } as $pass_result

    precondition ($pass_result) {
      error_type = "accessdenied"
      error = "Invalid Credentials."
    }

    // Generate token
    security.create_auth_token {
      table = "users"
      extras = {}
      expiration = 604800
      id = $user.id
    } as $authToken

    // Update last login
    db.edit "users" {
      field_value = $user.id
      data = { last_login: now }
    }
  }

  response = {
    authToken: $authToken
    user: {
      id: $user.id
      name: $user.name
      email: $user.email
    }
  }
}
```

### Get Current User (Protected Endpoint)

```xanoscript
query "auth/me" verb=GET {
  auth = "users"

  stack {
    db.get "users" {
      field_value = $auth.id
      output = ["id", "name", "email", "role", "created_at"]
    } as $user

    precondition ($user != null) {
      error_type = "notfound"
      error = "User not found"
    }
  }

  response = $user
}
```

### Role-Based Access

```xanoscript
query "admin/users" verb=GET {
  auth = "users"

  stack {
    db.get "users" { field_value = $auth.id } as $current_user

    precondition ($current_user.role == "admin") {
      error_type = "accessdenied"
      error = "Admin access required"
    }

    db.query users {
      sort = {created_at: "desc"}
      return = {type: "list", paging: {page: 1, per_page: 50}}
    } as $all_users
  }

  response = $all_users
}
```

### Ownership Check Pattern

```xanoscript
// Verify user owns the resource before allowing modification
db.get "posts" { field_value = $input.post_id } as $post

precondition ($post != null) {
  error_type = "notfound"
  error = "Post not found"
}

precondition ($post.user_id == $auth.id) {
  error_type = "accessdenied"
  error = "Not authorized to modify this post"
}
```

### Webhook Signature Verification

```xanoscript
query "webhooks/stripe" verb=POST {
  input { json payload }

  stack {
    var $raw_body { value = $input._raw_body }
    var $received_sig { value = $input._headers.stripe_signature }
    var $expected_sig { value = $raw_body|hmac_sha256:$env.STRIPE_WEBHOOK_SECRET }

    precondition ($received_sig == $expected_sig) {
      error_type = "unauthorized"
      error = "Invalid webhook signature"
    }

    // Process webhook event...
  }

  response = { received: true }
}
```

---

## Security Best Practices

1. **Same error message for user-not-found AND wrong-password** - Prevents user enumeration
2. **Use `error_type = "accessdenied"` for auth failures** - Returns 403
3. **Always trim and lowercase email** - `filters=trim|to_lower`
4. **Never store plain passwords** - Always hash with security methods
5. **Set reasonable token expiration** - 604800 (7 days) is common
6. **Check ownership before modify/delete** - Compare `$post.user_id == $auth.id`

---

## Quick Reference

| Method | Purpose | Key Params |
|---|---|---|
| `auth = "table"` | Require JWT auth | Table name (endpoint only) |
| `$auth.id` | Get authenticated user ID | Available after auth |
| `security.check_password` | Verify password | `text_password`, `hash_password` |
| `security.create_auth_token` | Generate JWT | `table`, `id`, `expiration`, `extras` |
| `\|sha256` | SHA256 hash | Filter on any string |
| `\|hmac_sha256:secret` | HMAC signature | For webhook verification |
| `\|base64_encode` | Base64 encode | Filter on any string |
| `""\|uuid` | Generate UUID | On empty string |

# What Doesn't Work in XanoScript

**Rule:** If something looks like it should work based on JavaScript/Python experience, check here first. XanoScript is a constrained DSL with strict limitations.

---

## Table of Contents
- [Syntax That Silently Fails or Throws](#syntax-that-silently-fails-or-throws)
- [Database Gotchas](#database-gotchas)
- [Filter Gotchas](#filter-gotchas)
- [Variable and Expression Gotchas](#variable-and-expression-gotchas)
- [API Request Gotchas](#api-request-gotchas)
- [Control Flow Gotchas](#control-flow-gotchas)

---

## Syntax That Silently Fails or Throws

### 1. No Ternary in WHERE Clauses

```xanoscript
// WRONG - "Ternary syntax is not supported in this context"
db.query items {
  where = ($input.status != null) ? ($db.items.status == $input.status) : true
}

// RIGHT - Use conditional branches
conditional {
  if ($input.status != null) {
    db.query items { where = $db.items.status == $input.status } as $items
  } else {
    db.query items {} as $items
  }
}
```

### 2. Invalid precondition error_type Values (runtime-verified 2026-02-20)

**CRITICAL:** error_type is validated at RUNTIME, not deploy time. Bad values deploy fine but explode when the precondition fires.

```xanoscript
// WRONG - These all deploy but FAIL at runtime:
precondition (...) { error_type = "invalid" }        // NOT VALID (common mistake!)
precondition (...) { error_type = "error" }          // NOT VALID
precondition (...) { error_type = "not_found" }      // NOT VALID (no underscore!)
precondition (...) { error_type = "field_error" }    // NOT VALID
precondition (...) { error_type = "fatal" }          // NOT VALID
precondition (...) { error_type = "bad_request" }    // NOT VALID (no underscore!)
precondition (...) { error_type = "input_error" }    // NOT VALID (no underscore!)

// RIGHT - ONLY these 7 values work:
precondition (...) { error_type = "standard" }          // 500 ERROR_FATAL
precondition (...) { error_type = "inputerror" }        // 400 ERROR_CODE_INPUT_ERROR
precondition (...) { error_type = "badrequest" }        // 400 ERROR_CODE_BAD_REQUEST
precondition (...) { error_type = "unauthorized" }      // 401 ERROR_CODE_UNAUTHORIZED
precondition (...) { error_type = "accessdenied" }      // 403 ERROR_CODE_ACCESS_DENIED
precondition (...) { error_type = "notfound" }          // 404 ERROR_CODE_NOT_FOUND
precondition (...) { error_type = "toomanyrequests" }   // 429 ERROR_CODE_TOO_MANY_REQUESTS

// RIGHT - Omit error_type for default (same as "standard", returns 500)
precondition (...) { error = "Something went wrong" }
```

### 3. Standalone paging Block in db.query

```xanoscript
// WRONG - "Invalid block: paging"
db.query users {
  paging = {page: 1, per_page: 10}
}

// WRONG - "Invalid block: filters"
db.query users {
  filters = {status: "active"}
}

// WRONG - "Invalid block: limit"
db.query users {
  limit = 10
}

// RIGHT - paging is INSIDE return, filtering uses where
db.query users {
  where = $db.users.status == "active"
  return = {type: "list", paging: {page: 1, per_page: 10}}
}
```

### 4. JSON-Style Filters in db.query

```xanoscript
// WRONG - "Input is not scalar"
db.query users {
  where = {status: "active"}
}

// WRONG - "Invalid block: filter"
db.query users {
  filter = {status: "active"}
}

// RIGHT - Use $db.table.field expression syntax
db.query users {
  where = $db.users.status == "active"
}
```

### 5. Unquoted Sort Direction

```xanoscript
// WRONG - Sort direction must be quoted
db.query users {
  sort = {created_at: desc}
}

// RIGHT
db.query users {
  sort = {created_at: "desc"}
}
```

### 6. db.delete Instead of db.del

```xanoscript
// WRONG - db.delete does not exist
db.delete "users" { field_value = $id }

// RIGHT
db.del "users" { field_value = $id }
```

### 7. content Instead of data in db.add/db.edit

```xanoscript
// WRONG - "content" throws error
db.add "users" { content = {name: "John"} }

// RIGHT
db.add "users" { data = {name: "John"} }
```

---

## Database Gotchas

### 8. |map:"field" is BROKEN in Raw XanoScript (runtime-verified 2026-02-20)

```xanoscript
// WRONG - "id is not defined" at runtime (deploys fine!)
var $ids { value = $query_result.items|map:"id" }

// WRONG - unquoted also fails
var $ids { value = $query_result.items|map:id }

// WRONG - variable reference also fails
var $field { value = "id" }
var $ids { value = $query_result.items|map:$field }

// RIGHT - Use foreach + |push (works in both endpoints and functions)
var $ids { value = [] }
foreach ($query_result.items) {
  each as $row {
    var.update $ids { value = $ids|push:$row.id }
  }
}
```

**Note:** foreach property access ($row.id, $row.action_text, etc.) WORKS fine.
The `|map` filter is what's broken in raw XanoScript (SDK-only).

### 9. Missing itemsTotal Without `totals: true` (runtime-verified 2026-02-20)

Xano skips calculating total count by default for performance. Without `totals: true`, `$result.itemsTotal` and `$result.pageTotal` simply **don't exist** in the response.

```xanoscript
// WRONG - "Unable to locate var: result.itemsTotal"
db.query users {
  return = {type: "list", paging: {page: 1, per_page: 20}}
} as $result
var $total { value = $result.itemsTotal }  // FAILS!

// RIGHT - Add totals: true to get itemsTotal and pageTotal
db.query users {
  return = {type: "list", paging: {page: 1, per_page: 20, totals: true}}
} as $result
var $total { value = $result.itemsTotal }  // 252
var $pages { value = $result.pageTotal }   // 13
```

**Without `totals: true`:** `itemsReceived`, `curPage`, `nextPage`, `prevPage`, `offset`, `perPage`
**With `totals: true`:** adds `itemsTotal` + `pageTotal`

**Note:** Including `"itemsTotal"` in the `output` filter does nothing if `totals: true` is missing. The field is silently dropped.

### 10. Dynamic Sort Field Variables

```xanoscript
// WRONG - Cannot use variables in sort field names
db.query posts { sort = {$input.sort_field: $input.sort_dir} }

// WRONG - Computed sort object doesn't work either
var $sort { value = {}|set:$field:$dir }
db.query posts { sort = $sort }

// RIGHT - Hardcode sort, use conditionals for options
conditional {
  if ($input.sort == "newest") {
    db.query posts { sort = {created_at: "desc"} } as $posts
  } else {
    db.query posts { sort = {created_at: "asc"} } as $posts
  }
}
```

### 11. ILIKE / Case-Insensitive Search

```xanoscript
// WRONG - ILIKE doesn't exist
db.query posts { where = $db.posts.title ILIKE $pattern }

// WRONG - ~* doesn't work ("Not numeric" error)
db.query posts { where = $db.posts.title ~* $pattern }

// RIGHT - Use |to_lower on BOTH sides
db.query posts {
  where = ($db.posts.title|to_lower) ~ ($input.search|to_lower)
}
```

---

## Filter Gotchas

### 12. |filter and |reduce Are SDK-Only

```xanoscript
// WRONG - "$item is not defined" in raw XanoScript
var $active { value = $users|filter:"$item.status == active" }
var $total { value = $prices|reduce:"$acc + $item":0 }

// RIGHT - Use foreach + conditional
var $active { value = [] }
foreach ($users) {
  each as $u {
    conditional {
      if ($u.status == "active") {
        var.update $active { value = $active|push:$u }
      }
    }
  }
}
```

**Note:** `|map:"field"` is BROKEN in raw XanoScript (runtime-verified 2026-02-20). Use foreach + `|push` instead.

### 13. |first_notempty and |first_notnull Are SDK-Only

```xanoscript
// WRONG - Syntax error in raw XanoScript
var $val { value = first_notempty:$a.name:"Unknown" }

// RIGHT - Use conditional
var $val { value = $a.name }
conditional {
  if ($val == null || $val == "") {
    var.update $val { value = "Unknown" }
  }
}
```

### 14. Non-Existent Filter Names

```xanoscript
// WRONG - These filters don't exist
$num|to_string    // Use |to_text
$num|toString     // Use |to_text
$arr|length       // Use |count
$arr|group_by:"f" // Use |index_by (one-per-key) or foreach
$val|default:[]   // Use conditional fallback

// RIGHT
$num|to_text
$arr|count
$arr|index_by:"field"
```

### 15. Array Element Lookup (No |index_of, No |contains on arrays)

```xanoscript
// WRONG - |index_of does NOT exist (deploy-time error: "Invalid filter name: index_of")
var $position { value = $array|index_of:$element }

// WRONG - |contains is string-only, not for arrays
var $found { value = $array|contains:$element }

// RIGHT - Use foreach to find element
var $found { value = false }
foreach ($array) {
  each as $row {
    conditional {
      if ($row == $element) {
        var.update $found { value = true }
      }
    }
  }
}

// RIGHT - For keyed lookups, use |index_by then |get
var $lookup { value = $items|index_by:"id" }
var $match { value = $lookup|get:$target_id:null }
```

---

## Variable and Expression Gotchas

### 16. Re-declaring Variables Instead of Updating

```xanoscript
// WRONG - Re-declare to update
var $count { value = 0 }
var $count { value = $count + 1 }  // Creates NEW var, doesn't update

// RIGHT - Use var.update
var $count { value = 0 }
var.update $count { value = $count + 1 }
```

### 17. Using $now Instead of now

```xanoscript
// WRONG - $now doesn't exist
var $time { value = $now }

// RIGHT - now is a bare keyword, no $ prefix
var $time { value = now }
```

### 18. Direct Arithmetic on Timestamps

```xanoscript
// WRONG - Arithmetic doesn't work on timestamps
var $tomorrow { value = now + 86400 }

// RIGHT - Use the filter
var $tomorrow { value = now|add_secs_to_timestamp:86400 }
```

### 19. Model Names with Special Characters

```xanoscript
// WRONG - Slash gets interpreted as divide
var $model { value = google/gemini-2.5-flash }
// Becomes: google|divide:gemini|subtract:2.5|subtract:flash

// RIGHT - Always quote strings with special chars
var $model { value = "google/gemini-2.5-flash" }
```

---

## API Request Gotchas

### 20. body Instead of params

```xanoscript
// WRONG - body doesn't exist
api.request {
  url = "https://api.example.com"
  method = "POST"
  body = $data            // WRONG keyword
}

// RIGHT
api.request {
  url = "https://api.example.com"
  method = "POST"
  params = $data          // CORRECT keyword
}
```

### 21. Assuming API Response Structure

```xanoscript
// WRONG - Response is nested deeper than you think
var $data { value = $result.data }

// RIGHT - Response nesting: $result.response.result for data
var $data { value = $result.response.result }
var $status { value = $result.response.status }

// ALWAYS check for timeout first
conditional {
  if ($result.response.result == false) {
    throw { name = "TIMEOUT" value = "API call timed out" }
  }
}
```

### 22. Step-by-Step Object Building (Performance)

```xanoscript
// WRONG - 600% slower (multiple var.update calls)
var $obj { value = {} }
var.update $obj { value = $obj|set:"a":$val1 }
var.update $obj { value = $obj|set:"b":$val2 }
var.update $obj { value = $obj|set:"c":$val3 }

// RIGHT - Chain in ONE expression
var $obj { value = {}|set:"a":$val1|set:"b":$val2|set:"c":$val3 }
```

---

## Control Flow Gotchas

### 23. foreach with "item" as Alias

```xanoscript
// WRONG - "item" shadows internal variable, silently returns empty
foreach ($users) {
  each as $item {
    var $name { value = $item.name }  // Empty/null!
  }
}

// RIGHT - Use any other alias
foreach ($users) {
  each as $row {
    var $name { value = $row.name }  // Works!
  }
}
```

### 24. Conditional else/elseif - Own Line, No Backticks (runtime-verified 2026-02-21)

`elseif` and `else` MUST start on their OWN LINE after the closing `}`. They do NOT need backticks. Parentheses work for all conditions.

```xanoscript
// WRONG - elseif/else on SAME LINE as closing brace → "Syntax error: unexpected '{'"
conditional {
  if ($status == "active") {
    var $msg { value = "Active" }
  } elseif ($status == "pending") {
    var $msg { value = "Pending" }
  } else {
    var $msg { value = "Other" }
  }
}

// WRONG - backticks around conditions (unnecessary and may cause issues)
conditional {
  if (`$status == "active"`) {
    var $msg { value = "Active" }
  }
}

// RIGHT - each keyword on its OWN LINE, parentheses for conditions
conditional {
  if ($status == "active") {
    var $msg { value = "Active" }
  }
  elseif ($status == "pending") {
    var $msg { value = "Pending" }
  }
  else {
    var $msg { value = "Other" }
  }
}

// RIGHT - if-only (no else) also works with own-line format
conditional {
  if ($input.name != "") {
    var.update $count { value = $count|add:1 }
  }
}
```

**Key rules:**
- `}` must be on its own line
- `elseif (condition) {` must be on the NEXT line (not same line as `}`)
- `else {` must be on the NEXT line (not same line as `}`)
- NO backticks needed - regular parentheses work
- `elseif` DOES exist and works. Nesting is NOT required.

### 24b. for/while Loop Syntax Requires `each` Block (runtime-verified 2026-02-20)

Loops exist in raw XanoScript but have specific syntax requirements.

```xanoscript
// WRONG - C-style for loop
for ($i = 0; $i < 5; $i++) { ... }  // "unexpected 'var.update'"

// WRONG - while without each block
while ($counter < 5) {
  var.update $counter { value = $counter|add:1 }  // "unexpected 'var.update'"
}

// RIGHT - for loop with count and each block (0-indexed)
for (5) {
  each as $i {
    var.update $results { value = $results|push:$i }  // $i = 0,1,2,3,4
  }
}

// RIGHT - while loop with each block (no alias)
while ($counter < 5) {
  each {
    var.update $counter { value = $counter|add:1 }
  }
}
```

**Key syntax rules:**
- `for` takes a count in parens: `for (N)` - NOT C-style `for (init; cond; incr)`
- `for` requires `each as $varname` block
- `while` takes a condition in parens: `while ($condition)`
- `while` requires `each` block (NO alias - just `each { }`)
- `break` and `continue` work inside for/while/foreach
- Index is 0-based for `for` loops

### 24c. switch/case - BROKEN at Runtime (runtime-verified 2026-02-21)

**WARNING:** switch/case DEPLOYS fine but case matching NEVER WORKS at runtime. All cases fall through to `default`. Use conditional if/elseif instead.

```xanoscript
// DEPLOYS but BROKEN - always hits default regardless of $val value
switch ($val) {
  case expr="apple" {
    var.update $result { value = "fruit_a" }    // Never reached!
  }
  case expr="banana" {
    var.update $result { value = "fruit_b" }    // Never reached!
  }
  default {
    var.update $result { value = "unknown" }    // Always hits this
  }
}

// RIGHT - Use conditional if/elseif instead
conditional {
  if ($val == "apple") {
    var.update $result { value = "fruit_a" }
  }
  elseif ($val == "banana") {
    var.update $result { value = "fruit_b" }
  }
  else {
    var.update $result { value = "unknown" }
  }
}
```

**Tested and failed:** `case expr="value"`, `case expr=($var == "value")`, `case "value" expr="value"`, `switch (true)` with boolean case expr. None of these matched at runtime.

### 24d. join/eval Errors Are ALWAYS Wrong Table or Field Names (runtime-verified 2026-02-20)

**CRITICAL:** Join syntax deploys fine but errors at runtime are ALWAYS caused by wrong table names or wrong field names. ALWAYS use `list_tables` and `get_table_schema` to verify before writing joins.

```xanoscript
// WRONG - "missing bind parameter - dbo" (table "transcripts" doesn't exist!)
db.query action_items {
  join = {
    t: { table: "transcripts", where: $db.action_items.transcript_id == $db.t.id }
  }
} as $result

// WRONG - "Unsupported parameter reference - xdo.title" (field is "meeting_title" not "title")
db.query action_items {
  join = {
    kt: { table: "krisp_transcripts", where: $db.action_items.transcript_id == $db.kt.id }
  }
  eval = { title: $db.kt.title }
} as $result

// RIGHT - Correct table name + correct field name
db.query action_items {
  join = {
    kt: { table: "krisp_transcripts", where: $db.action_items.transcript_id == $db.kt.id }
  }
  eval = { meeting_title: $db.kt.meeting_title }
  output = ["items.id", "items.action_text", "items.meeting_title"]
} as $result
```

**Also WRONG:** Using `type: "left"` or `type: "inner"` in the join block. Official XanoScript join only takes `table` and `where`.

### 24e. Addon Input Field References - Only `$output.field` Works (runtime-verified 2026-02-20)

```xanoscript
// WRONG - quoted string, addon returns null silently
addon = [{name: "Lora Model", input: {lora_models_id: "$output.lora_model_id"}, as: "items.lora_info"}]

// WRONG - plain string, addon returns null silently
addon = [{name: "Lora Model", input: {lora_models_id: "lora_model_id"}, as: "items.lora_info"}]

// WRONG - $db reference, syntax error "Unknown kind for static object: assign:db"
addon = [{name: "Lora Model", input: {lora_models_id: $db.CHAT_companions.lora_model_id}, as: "items.lora_info"}]

// RIGHT - $output.field as expression (no quotes!)
addon = [{name: "Lora Model", input: {lora_models_id: $output.lora_model_id}, as: "items.lora_info"}]
```

**Also:** `addons` (plural) is "Invalid block". Use `addon` (singular) with array syntax `[{...}]`.

### 24f. `search` Is NOT a Valid db.query Block (runtime-verified 2026-02-20)

The addon definition docs show `search = $db.table.field == value` but this is NOT valid in actual db.query deployment: "Invalid block: search". Use `where =` instead.

### 25. db.edit data = $variable FAILS

```xanoscript
// WRONG - "Invalid kind for data - assign:var"
var $update_data { value = {}|set:"name":$input.name|set:"status":$input.status }
db.edit "items" {
  field_name = "id"
  field_value = $input.id
  data = $update_data       // FAILS - can't use variable!
}

// RIGHT - Use inline data object with individual variable references
var $f_name { value = $existing.name }
var $f_status { value = $existing.status }
conditional {
  if ($input.name != null && $input.name != "") {
    var.update $f_name { value = $input.name }
  }
}
conditional {
  if ($input.status != null && $input.status != "") {
    var.update $f_status { value = $input.status }
  }
}
db.edit "items" {
  field_name = "id"
  field_value = $input.id
  data = {
    name: $f_name
    status: $f_status
  }
}
```

### 26. Endpoint Requires input {} Block

```xanoscript
// WRONG - "Missing input block" at deploy time
query "test" verb=GET {
  stack {
    var $msg { value = "hello" }
  }
  response = { message: $msg }
}

// RIGHT - Include empty input {} even if no parameters
query "test" verb=GET {
  input {}
  stack {
    var $msg { value = "hello" }
  }
  response = { message: $msg }
}
```

### 28. try/catch Does NOT Work in Raw XanoScript (deploy-time verified 2026-02-20)

```xanoscript
// WRONG - "Syntax error: unexpected 'try'"
try {
  api.request { ... } as $result
} catch ($error) {
  var $msg { value = $error.message }
}

// WRONG - try_catch wrapper also fails on nested blocks
try_catch {
  try {
    var $x { value = "test" }
  } catch ($error) {
    var $x { value = "error" }
  }
}

// RIGHT - Use the null-as-success pattern (production-verified)
var $result { value = null }
// ... do operations ...
conditional {
  if ($some_check == false) {
    var.update $result { value = {}|set:"success":false|set:"error":"Something failed" }
  }
}
conditional {
  if ($result == null) {
    var.update $result { value = {}|set:"success":true|set:"data":$data }
  }
}
```

**Use conditionals to check API response status instead of try/catch.**

### 29. Special Characters in String Values

```xanoscript
// WRONG - Apostrophes break JSON serialization
var $prompt { value = $companion.system_prompt }
// If contains "You're creative" → JSON syntax error downstream

// RIGHT - Test with simple strings first, escape if needed
var $prompt { value = $companion.system_prompt|replace:"'":"" }
```

### 30. Default Values with Spaces in Input

```xanoscript
// WRONG - "Syntax error: unexpected 'World'"
input {
  text name?=Hello World
}

// RIGHT - No spaces in default values (use single word or no space)
input {
  text name?=HelloWorld
}

// RIGHT - Or just make it required
input {
  text name
}
```

**Note:** Default values cannot contain spaces. Use underscores or camelCase instead.

### 31. Many Filters are SDK-Only (deploy-time error: "Invalid filter name")

The following filters exist in Xano's internal registry but **DO NOT EXIST** in raw XanoScript:

| SDK-Only Filter | Use Instead |
|---|---|
| `\|explode:sep` | No raw equivalent for string split |
| `\|implode:sep` | `\|join:sep` |
| `\|at:n` | `\|slice:n:1\|first` |
| `\|index_of:val` | foreach to find |
| `\|pad_left`, `\|pad_right` | No raw equivalent |
| `\|snake_case`, `\|camel_case`, `\|pascal_case`, `\|kebab_case` | No raw equivalent |
| `\|word_count` | No raw equivalent |
| `\|sort_by:"field"` | Use `db.query sort` or foreach |
| `\|delete:"key"` | `\|unset:"key"` |
| `\|is_numeric`, `\|is_empty`, `\|is_null`, `\|is_array`, `\|is_email`, `\|is_url` | Use `== null` or `== ""` in conditional |

### 32. |transform_timestamp Returns "0" (Use |format_timestamp)

```xanoscript
// WRONG - Returns "0" at runtime
var $date { value = now|transform_timestamp:"Y-m-d" }

// RIGHT - Use format_timestamp instead
var $date { value = now|format_timestamp:"Y-m-d" }
```

---

## Quick Diagnostic Table

| Error Message | Cause | Fix |
|---|---|---|
| "Invalid block: paging" | Standalone paging in db.query | Put inside `return = {type: "list", paging: {...}}` |
| "Invalid block: filters" | Using filters in db.query | Use `where = $db.table.field == value` |
| "Invalid block: filter" | Using filter in db.query | Use `where = $db.table.field == value` |
| "Input is not scalar" | JSON object in where | Use `$db.table.field` notation |
| "Ternary syntax is not supported" | `? :` in WHERE | Use conditional branches |
| "Input 'X' is not one of the allowable values" | Invalid error_type (runtime!) | Use: standard, inputerror, badrequest, unauthorized, accessdenied, notfound, toomanyrequests |
| "X is not defined" (in \|map context) | `\|map:"field"` broken in raw XanoScript | Use foreach + `\|push:$row.field` instead |
| "$item is not defined" | Using `\|filter` in raw XanoScript | Use foreach + conditional |
| "Not numeric" | Using ~* operator | Use `(\|to_lower) ~ (\|to_lower)` |
| "Syntax error: unexpected '{'" | else/elseif on same line as `}` | Put each on OWN LINE after `}` |
| "Invalid kind for data - assign:var" | `data = $variable` in db.edit | Use inline data object with field variables |
| "Missing input block" | Endpoint without `input {}` | Add `input {}` even if empty |
| "Syntax error: unexpected 'try'" | `try { }` in raw XanoScript | Use null-as-success pattern with conditionals |
| "Invalid filter name: index_of" | `\|index_of` does not exist | Use foreach to find elements |
| "Invalid filter name: explode" | `\|explode` is SDK-only | No raw equivalent for string split |
| "Invalid filter name: implode" | `\|implode` is SDK-only | Use `\|join:sep` instead |
| "Invalid filter name: at" | `\|at` is SDK-only | Use `\|slice:n:1\|first` |
| "Invalid filter name: pad_left" | `\|pad_left` is SDK-only | No raw equivalent |
| "Invalid filter name: snake_case" | `\|snake_case` is SDK-only | No raw equivalent |
| "Invalid filter name: word_count" | `\|word_count` is SDK-only | No raw equivalent |
| "Invalid filter name: delete" | `\|delete` is SDK-only | Use `\|unset:"key"` |
| "Invalid filter name: is_numeric" | Validation filters are SDK-only | Use conditional checks |
| "Syntax error: unexpected 'X'" | Space in default value `?=Hello World` | No spaces in defaults |
| Returns "0" | `\|transform_timestamp` broken | Use `\|format_timestamp` instead |
| "Invalid filter name: count == 0" | Filter in conditional | Store `\|count` in variable first, then compare |
| "error code: 524" | URL with special chars in default | Don't use URLs as default values in input |
| "Missing var entry: remote_ip" | System env var not available | Visual-builder-only - not in raw XanoScript |
| "Missing var entry: http_headers" | System env var not available | Visual-builder-only - not in raw XanoScript |
| "unexpected 'db.count'" | db.count doesn't exist | Use `db.query { return = {type: "count"} }` |
| "unexpected 'db.addOrEdit'" | db.addOrEdit doesn't exist | Use db.has + conditional + db.add/db.edit |
| "unexpected 'db.bulkAdd'" | db.bulkAdd doesn't exist | Use foreach + db.add |
| "Missing block2: field_value" | db.has uses field_value, not where | `db.has "t" { field_name = "f", field_value = $v }` |
| "Invalid filter name: sort_by" | `\|sort_by` is SDK-only | Use `db.query sort` or foreach |

---

## Equality Gotchas

### 33. Loose Equality - null/empty/false/zero/[] (runtime-verified 2026-02-20)

**CRITICAL:** XanoScript uses loose equality. These all evaluate to TRUE:

```xanoscript
// ALL of these are TRUE:
null == ""      // true! Can't distinguish null from empty string
null == 0       // true!
null == false   // true!
0 == false      // true!
false == ""     // true!
[] == null      // true! Empty array equals null!

// This one is FALSE:
0 == ""         // false! (only exception)
```

**Consequences:**
- You cannot reliably distinguish `null` from `""` using `==`
- `$var == null` is true for null, "", false, 0, AND empty arrays
- Use `!= null && != ""` together for "has a real value" checks
- Empty arrays `[]` are considered equal to `null`

### 34. Filter Results Cannot Be Used Directly in Conditionals

```xanoscript
// WRONG - "Invalid filter name: count == 0"
conditional {
  if ($arr|count == 0) {
    // ...
  }
}

// RIGHT - Store filter result in variable first
var $arr_len { value = $arr|count }
conditional {
  if ($arr_len == 0) {
    // ...
  }
}
```

**Rule:** Always store filter results in a variable before using in conditionals, preconditions, or other comparisons.

### 35. Input Default Values Cannot Contain Special Characters

```xanoscript
// WRONG - error code 524 (silent deploy failure)
input {
  text url?=https://example.com/api
}

// RIGHT - No URLs, colons, or slashes in defaults
input {
  text url   // Make it required, pass the URL at call time
}
```

### 36. api.request method Can Be a Variable

```xanoscript
// This WORKS - method can be dynamic
api.request {
  url = $input.url
  method = $input.http_method   // Variable, not just literal "POST"!
  params = $data
  headers = []|push:"Content-Type: application/json"
  timeout = 30
} as $result
```

### 37. These Standalone Commands DO NOT EXIST (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "unexpected 'db.count'" - db.count does NOT exist
db.count "action_items" { where = ... } as $count

// WRONG - "unexpected 'db.addOrEdit'" - db.addOrEdit does NOT exist
db.addOrEdit "table" { field_name = "email", field_value = $email, data = {...} }

// WRONG - "unexpected 'db.bulkAdd'" - bulk ops do NOT exist
db.bulkAdd "table" { data = $records }
db.bulkUpdate "table" { filters = {...}, data = {...} }
db.bulkDelete "table" { filters = {...} }

// RIGHT - Use db.query with return types for counts/exists
db.query table { where = ..., return = {type: "count"} } as $count
db.query table { where = ..., return = {type: "exists"} } as $exists

// RIGHT - Use db.get + conditional + db.add/db.edit for upsert
db.has "table" { field_name = "email", field_value = $email } as $exists
conditional {
  if ($exists) {
    db.edit "table" { field_name = "email", field_value = $email, data = {...} }
  }
  else {
    db.add "table" { data = {...} }
  }
}

// RIGHT - Use foreach for bulk operations
foreach ($records) {
  each as $row {
    db.add "table" { data = { name: $row.name } }
  }
}
```

### 38. db.has Uses field_value Syntax, NOT where (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "Missing block2: field_value"
db.has action_items { where = $db.action_items.status == "pending" } as $exists

// RIGHT - Uses field_value syntax (like db.get)
db.has "action_items" {
  field_name = "status"
  field_value = "pending"
} as $exists  // returns true/false

// RIGHT - Default field_name is "id"
db.has "action_items" { field_value = 1973 } as $exists
```

### 39. $server and $header Variables Do NOT Exist (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "Missing var entry: server"
var $info { value = $server }

// WRONG - "Missing var entry: header"
var $info { value = $header }

// These variables simply don't exist in raw XanoScript endpoints.
// Available special variables: $input, $auth, $env, now
```

### 40. |sort_by and |pick Multi-Key Are Broken (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "Invalid filter name: sort_by" - SDK only
var $sorted { value = $items|sort_by:"name" }

// RIGHT - Use db.query sort for database results, or |sort for simple arrays
db.query items { sort = {name: "asc"} } as $sorted
var $nums_sorted { value = $nums|sort }  // ascending only

// |pick ONLY picks the FIRST key - multiple keys are silently ignored!
var $obj { value = {}|set:"a":1|set:"b":2|set:"c":3 }
var $picked { value = $obj|pick:"a":"c" }  // Returns {a: 1} NOT {a:1, c:3}!

// RIGHT - For multiple keys, chain |pick calls or build new object
var $subset { value = {}|set:"a":($obj|get:"a":null)|set:"c":($obj|get:"c":null) }

// |unpick works correctly for removing keys
var $without_b { value = $obj|unpick:"b" }  // Returns {a:1, c:3} ✓
```

### 41. security.create_auth_token Uses `table` NOT `auth` (runtime-verified 2026-02-21)

```xanoscript
// WRONG - "Invalid block: auth"
security.create_auth_token {
  auth = "🔐 [AUTH] users"
  id = $user.id
  extras = {}
  expiration = 3600
} as $token

// RIGHT - Use `table` keyword. ALL 4 blocks are REQUIRED.
security.create_auth_token {
  table = "🔐 [AUTH] users"
  id = $user.id
  extras = {}
  expiration = 3600
} as $token

// extras can include custom JWT claims
security.create_auth_token {
  table = "🔐 [AUTH] users"
  id = $user.id
  extras = {}|set:"role":"admin"|set:"custom_claim":"value"
  expiration = 3600
} as $token
```

### 42. db.query return={type:"stream"} Returns Marker, Not Data (runtime-verified 2026-02-21)

```xanoscript
// Deploys fine but returns "@stream" string marker, not actual data
db.query items { return = {type: "stream"} } as $result
// $result == "@stream" (string literal, not usable data)

// return={type:"aggregate"} requires separate aggregate block (syntax TBD)
db.query items { return = {type: "aggregate"} } as $result
// → "Aggregate block is empty" error
```

### 37. $env Missing Keys Return null (Not Error)

```xanoscript
// Missing env vars DON'T throw - they return null
var $key { value = $env.NONEXISTENT_KEY }
// $key is now null (and null == "" is true!)

// RIGHT - Check with explicit null AND empty
conditional {
  if ($key != null && $key != "") {
    // Key exists and has a value
  }
}
```

### 43. System Environment Variables Are Visual-Builder-Only (runtime-verified 2026-02-21)

These 7 system variables exist in Xano's visual builder dropdown but are **NOT accessible** in raw XanoScript deployed via MCP:

| Variable | Purpose | Available in Raw XanoScript? |
|---|---|---|
| `$remote_ip` | Client IP address | NO - "Missing var entry: remote_ip" |
| `$http_headers` | Request headers (text array) | NO - "Missing var entry: http_headers" |
| `$request_uri` | Request URI path | NO - "Missing var entry: request_uri" |
| `$request_method` | HTTP method (GET/POST/etc) | NO - "Missing var entry: request_method" |
| `$request_querystring` | Raw query string | NO - "Missing var entry: request_querystring" |
| `$datasource` | Current datasource (live/test) | NO - "Missing var entry: datasource" |
| `$branch` | Current branch name | NO - "Missing var entry: branch" |
| `$request_auth_token` | Bearer token from header | NO - undocumented |
| `$tenant` | Tenant identifier | NO - undocumented |
| `$debugger` | Debugger flag | NO - undocumented |

**None of these work as `$var`, `$env.var`, `$_server`, or `$request`.**

**What DOES work for environment access:**
- `$env.KEY` - User-defined environment variables (set in Xano dashboard)
- `$input` - Declared input parameters
- `$auth` - Authenticated user data
- `now` - Current timestamp
- `util.get_env {} as $all_env` - Dumps ALL user env vars (see #44)

### 44. Utility Functions That DO Work (runtime-verified 2026-02-21)

These `util.*` functions are available in raw XanoScript:

```xanoscript
// Get ALL user-defined environment variables as one object
// WARNING: Exposes ALL secrets (API keys, tokens, etc.) - never put in response!
util.get_env {} as $all_env
// $all_env.OPENAI_API_KEY, $all_env.STRIPE_SECRET, etc.

// Get ALL raw input (including undeclared params not in input{})
util.get_input {} as $raw_input
// Useful for catching extra query params not declared in input block

// Get only DECLARED inputs (matching input{} block)
util.get_all_input {} as $declared_input

// Get all in-scope variables
util.get_vars {} as $all_vars

// Set custom response header
util.set_header { name = "X-Custom" value = "custom-value" }

// Sleep/delay (in milliseconds)
util.sleep { value = 1000 }

// IP geolocation lookup
util.ip_lookup { value = "8.8.8.8" } as $geo

// Calculate distance between coordinates
util.geo_distance {
  lat1 = 40.7128
  lon1 = -74.0060
  lat2 = 34.0522
  lon2 = -118.2437
} as $distance
```

**Key distinction:**
- `util.get_input {}` → ALL raw input (includes undeclared params like extra query params)
- `util.get_all_input {}` → ONLY declared inputs (matches `input {}` block)

---

**Status**: Production-verified from 302+ functions and 6+ months development
**Updates**: Add new gotchas as discovered

# Incremental Build-Test-Update Workflow

**The workflow is everything. Skip it and you'll build errors on top of errors.**

---

## The Golden Rule

```
BUILD ONE THING → TEST IT → LEARN → UPDATE (not recreate) → REPEAT
```

---

## Step 1: Create Minimal Endpoint

Start with the absolute minimum - just input validation and a hardcoded response.

```xanoscript
query "items/create" verb=POST {
  api_group = "Items API"

  input {
    text name
  }

  stack {
    precondition ($input.name != "") {
      error_type = "inputerror"
      error = "Name is required"
    }
  }

  response = { success: true, message: "Validation passed" }
}
```

**Deploy:** `create_endpoint`
**Test:** curl immediately
**Verify:** Does it return `{success: true}`?

---

## Step 2: Add ONE Feature

Based on Step 1 results, add exactly ONE operation.

```xanoscript
query "items/create" verb=POST {
  api_group = "Items API"

  input {
    text name
  }

  stack {
    precondition ($input.name != "") {
      error_type = "inputerror"
      error = "Name is required"
    }

    db.add "items" {
      data = { name: $input.name, created_at: now }
    } as $new_item
  }

  response = { success: true, item: $new_item }
}
```

**Deploy:** `update_endpoint` (NEVER create a new one!)
**Test:** curl again
**Verify:** Does the record appear in the database?

---

## Step 3: Keep Adding ONE Feature at a Time

Each iteration:
1. Look at previous test results
2. Add ONE new feature (auth, query, conditional, etc.)
3. UPDATE the same endpoint
4. Test with curl
5. Learn from the actual response
6. Repeat

---

## What NOT to Do

### Never Build Everything at Once

```xanoscript
// THIS WILL FAIL with 5-10 errors at once
query "items/create" verb=POST {
  auth = "users"
  input { text name, text status?, int category_id }
  stack {
    precondition (...)
    db.query categories { ... }
    precondition (...)
    db.add items { ... }
    db.edit categories { ... }
    function.run "Notifications/send" { ... }
  }
  response = { ... complex ... }
}
```

Each operation is a potential error. Fix 1 error at a time, not 10.

### Never Create Duplicate Endpoints

```
BAD:  /items/create → /items/create-v2 → /items/create-v3
GOOD: /items/create → update → update → update
```

Always use `update_endpoint` after the first `create_endpoint`.

### Never Skip Testing

```
BAD:  Create → Add 5 features → Test → 10 errors
GOOD: Create → Test → Add 1 → Test → Add 1 → Test
```

### Never Assume Response Structure

```xanoscript
// DON'T assume this path works
var $data { value = $result.data }

// DO test first, then read the actual response to learn the path
// api.request responses are nested: $result.response.result
// db.query responses have: $result.items, $result.itemsReceived, $result.curPage, etc.
// NOTE: $result.itemsTotal ONLY exists with totals: true in paging!
```

---

## MCP Tool Usage

### First Deployment

```
1. tool_search → find "create endpoint"
2. info → get exact parameters for create_endpoint
3. execute create_endpoint → deploy minimal XanoScript
4. curl test → verify
```

### Every Update After

```
1. execute update_endpoint → with api_id from first create
2. curl test → verify
3. repeat
```

### Key Parameters

| Tool | When | Key Params |
|---|---|---|
| `create_endpoint` | First time only | `api_group_id`, `name`, `method`, `xanoscript` |
| `update_endpoint` | Every change after | `api_id`, `xanoscript` |
| `create_function` | New function | `folder`, `name`, `xanoscript` |
| `update_function` | Modify function | `function_id`, `xanoscript` |
| `create_task` | New background task | `name`, `xanoscript` |
| `update_task` | Modify task | `task_id`, `xanoscript` |

---

## Before Writing Any XanoScript

1. **Search patterns first**: Use `xano_pattern_search` to find working examples
2. **Check closed sets**: Verify every value against [closed-sets.md](closed-sets.md)
3. **Check what doesn't work**: Read [what-doesnt-work.md](what-doesnt-work.md)
4. **Start minimal**: Don't try to be clever on the first deploy

---

## When Something Fails

1. Read the EXACT error message
2. Check [what-doesnt-work.md](what-doesnt-work.md) for that error
3. Simplify to minimal test case
4. Hardcode all values
5. Test the minimal version
6. Add complexity back one piece at a time

**Never guess. Never brute force. Always test incrementally.**

---

## Workflow Checklist

For every endpoint/function/task:

- [ ] Started with minimal version (input + hardcoded response)
- [ ] Tested with curl after first deploy
- [ ] Added features ONE at a time
- [ ] Used `update_*` not `create_*` for changes
- [ ] Tested after EVERY change
- [ ] Read actual response (not assumed)
- [ ] All error_type values are from the valid set of 7
- [ ] All db.query blocks are from the valid set of 4
- [ ] Sort directions are quoted strings