# Xano — LLMs & Agents Guide (Full)

> A comprehensive guide for LLMs and agents to understand and use Xano effectively: concepts, terminology, best practices, examples, do/don’t rules, and authoritative links.

## Goals
- Answer Xano questions factually and concisely, citing canonical docs.
- Provide correct procedural steps for common tasks (APIs, DB, auth, background tasks, external APIs, AI/Agents/Actions).
- Avoid stale, plan-specific, or speculative details; prefer links with recency notes.

## Golden rules for responses
1) Prefer official docs and use the same terminology as the Xano UI (Function Stack, Add-ons, Background Tasks, Agents, Actions, API Groups).
2) Summarize narrowly. Link to the exact doc page and section when possible.
3) Warn about plan/pricing variability. Verify effective dates when relevant.
4) Avoid hallucinations. If unknown or ambiguous, state assumptions or ask for the missing detail.
5) Provide runnable examples (e.g., curl) when appropriate; otherwise, outline Function Stack steps.

## How to use this file (retrieval prompt)
- If the user asks “how to” or “what is” about Xano, search this file first, then open the referenced doc pages.
- When summarizing, cite the link(s) you used. Example: [Docs index](https://docs.xano.com/), [Query All Records](https://docs.xano.com/the-function-stack/functions/database-requests/query-all-records).
- Use the “Recipes” section for quickly assembling step-by-step answers.

---

## Overview
- Xano is a backend platform with a managed PostgreSQL database, a visual Function Stack for APIs and logic, and features like Background Tasks, External API requests, and AI tools (Agents/Actions).
- Most work happens via: Database (tables/fields/relationships), API Groups (endpoints), and the Function Stack (steps/operations inside each endpoint). See: [APIs in Xano](https://docs.xano.com/the-function-stack/building-with-visual-development/apis)

## Quick links (start here)
- Homepage: https://www.xano.com/
- Docs index: https://docs.xano.com/
- Pricing: https://www.xano.com/pricing/ (always verify recency)

## Core concepts
- Database basics: https://docs.xano.com/the-database/database-basics
- Field types: https://docs.xano.com/the-database/database-basics/field-types
- Data types (Function Stack): https://docs.xano.com/the-function-stack/data-types
- APIs in Xano: https://docs.xano.com/the-function-stack/building-with-visual-development/apis
- Query All Records: https://docs.xano.com/the-function-stack/functions/database-requests/query-all-records
- Direct Database Query: https://docs.xano.com/the-function-stack/functions/database-requests/direct-database-query
- Filters: https://docs.xano.com/the-function-stack/filters
- External API Request: https://docs.xano.com/the-function-stack/functions/apis-and-lambdas/external-api-request
- Background Tasks: https://docs.xano.com/the-function-stack/building-with-visual-development/background-tasks
- User Auth & User Data: https://docs.xano.com/building-backend-features/user-authentication-and-user-data
- Agents: https://docs.xano.com/ai-tools/agents
- Actions: https://docs.xano.com/xano-actions/what-are-actions
- Metadata API: https://docs.xano.com/xano-features/metadata-api
- Developer API (learn): https://www.xano.com/learn/Developer-API/

## Terminology and objects
- Workspace: A self-contained project area with its own DB, APIs, tasks, etc.
- API Group: A collection of endpoints under a shared base URL.
- Endpoint: An HTTP route with inputs/outputs and a Function Stack defining its behavior.
- Function Stack: Visual step-by-step logic builder (query, transform, external API, conditionals, etc.).
- Add-on: GraphQL-like enrichment of response with related records without manual join queries.
- Background Task: Scheduled or recurring job (cron-like) for non-interactive processing.
- Agent: AI-enabled process with tools/actions; can run long-lived workflows.
- Action: Reusable unit of logic; callable from endpoints, Background Tasks, or Agents.

---

## Database
- See: [Database basics](https://docs.xano.com/the-database/database-basics), [Field types](https://docs.xano.com/the-database/database-basics/field-types)
- Relationships: Define references between tables (one-to-one, one-to-many, many-to-many via join tables).
- Files/Images: Stored as references; actual file storage managed by Xano; fields hold metadata/links.
- Common fields: `id`, `created_at`, `updated_at`, optional `deleted_at` for soft deletes.

### Data types (Function Stack)
- See: [Data types](https://docs.xano.com/the-function-stack/data-types)
- Includes: Text, Integer, Decimal, Boolean, Timestamp, Array, Object, Null.
- Arrays/Objects are first-class; Filters provide transformations.

### Querying
- Primary: [Query All Records](https://docs.xano.com/the-function-stack/functions/database-requests/query-all-records)
- Advanced: [Direct Database Query](https://docs.xano.com/the-function-stack/functions/database-requests/direct-database-query)
- Pagination: page/limit (or offset), sorting, searching, aggregations.

### Add-ons vs Joins
- Concept: Add-ons enrich returned records with related data (like GraphQL selection).
- Learn: https://www.xano.com/learn/joins-vs-addons/
- Sorting/filtering add-ons: https://www.xano.com/learn/filter-and-sort-addons/
- Prefer Add-ons to avoid N+1 queries; return types can be single, list, count, existence, etc.

---

## APIs and the Function Stack
- Build endpoints in API Groups; each endpoint has a Function Stack.
- Common steps: Input validation → Query/Create/Update/Delete → Filters → External API → Return response.

### Filters
- See: [Filters](https://docs.xano.com/the-function-stack/filters)
- Categories: Manipulation, Math, Timestamp, Text, Array, Transform, Conversion, Comparison, Security.
- Use Filters for mapping/transforming payloads, sanitizing input, deriving fields, shaping outputs.

### Error handling
- Pattern: Return an object with `status`, `message`, and optionally `code`/`details`.
- Use conditional steps to early-return on invalid input, record not found, or external API failures.

### Example: Basic list endpoint (conceptual)
```text
Inputs: page, limit, search, sort
1) Query All Records → table: products → with filters/search
2) Add-ons → include category (single), images (list)
3) Filters → map fields; compute derived properties (e.g., price_with_tax)
4) Return { items, pagination, total }
```

### Example: cURL usage
```bash
# List products
curl -s "https://<workspace>-<region>.xano.io/api:<group>/products?page=1&limit=20" \
  -H "Authorization: Bearer <token>"
```

---

## Authentication
- Docs: [User Authentication & User Data](https://docs.xano.com/building-backend-features/user-authentication-and-user-data)
- Tokens: JSON Web Encryption (JWE). Configure lifetime/refresh behavior in auth settings.

### Typical flow
1) Sign up
2) Login → receive token
3) Call protected endpoints with `Authorization: Bearer <token>` header

```bash
curl -X POST "https://<workspace>-<region>.xano.io/api:<group>/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret"}'

curl -X GET "https://<workspace>-<region>.xano.io/api:<group>/users/me" \
  -H "Authorization: Bearer <token>"
```

---

## Background Tasks
- Docs: [Background Tasks](https://docs.xano.com/the-function-stack/building-with-visual-development/background-tasks)
- Use for emails, report generation, analytics, imports/ETL, long-running jobs.
- Prefer tasks to keep user-facing endpoints fast. Schedule with cron-like settings.

---

## External API Requests
- Docs: [External API Request](https://docs.xano.com/the-function-stack/functions/apis-and-lambdas/external-api-request)
- Configure method, URL, headers, auth, and parsing. Handle timeouts/retries.

Example (conceptual):
```text
1) External API Request → GET https://api.example.com/data
2) If error → return { status:"error", message, upstream_status }
3) Filters → map/normalize response to your schema
4) Return structured object/list
```

---

## Agents and Actions (AI)
- Agents: https://docs.xano.com/ai-tools/agents
- Actions overview: https://docs.xano.com/xano-actions/what-are-actions
- Use Actions to encapsulate reusable, composable logic; call from endpoints, Background Tasks, or Agents.

---

## Management & Programmatic Access
- Metadata API (introspect schema, fields, relationships): https://docs.xano.com/xano-features/metadata-api
- Developer API (automation & dev workflows): https://www.xano.com/learn/Developer-API/
- Enterprise connectivity (Xano Link): https://docs.xano.com/enterprise/enterprise-features/xano-link

---

## Performance best practices
- Avoid N+1: prefer Add-ons over per-record queries.
- Paginate results and request only necessary fields.
- Offload heavy work to Background Tasks.
- Use stable, cacheable responses where feasible; ensure idempotency for retries.

## Security best practices
- Use auth-protected API Groups for sensitive endpoints.
- Validate input and sanitize using Filters; never concatenate untrusted strings into queries.
- Store secrets in environment-specific configuration; never hard-code secrets.

## Observability & troubleshooting
- Inspect each Function Stack step’s inputs/outputs.
- Return consistent error shapes; include upstream status codes/messages when calling external APIs.
- Log enough context to correlate failures without leaking PII.

---

## Common patterns & recipes

### Upsert
```text
1) Query record by unique key
2) If found → Update; else → Create
3) Return record
```

### Soft delete
```text
1) Update record → set deleted_at = now()
2) In queries → filter deleted_at IS NULL
```

### Slug generation (unique)
```text
1) Create base slug via Filters (e.g., lower-case, replace spaces)
2) Check for conflicts → append suffix if needed
3) Save and return
```

### Pagination response shape
```json
{
  "items": [/* ... */],
  "page": 1,
  "limit": 20,
  "total": 123,
  "has_next": true
}
```

### Aggregations
- Use Query All Records with aggregation options, or pre-compute via Background Tasks for analytics dashboards.

### File/image handling
- Store via file/image field types. Return signed URLs or public links depending on privacy needs.

---

## Environment, branching, deployment
- Workspaces can have environment-like setups. For CI/CD, use Developer API/Metadata API for automation.
- Keep environment-specific secrets and endpoints separate; never mix staging and production credentials.

---

## Rate limits, quotas, pricing
- Plans and limits change. Always confirm on [Pricing](https://www.xano.com/pricing/) and [Increasing plan limits](https://docs.xano.com/increasing-plan-limits).
- When answering capacity questions, note the date and advise verifying the plan page.

---

## FAQ (concise)
- How do I join data? → Use Add-ons for related records; see “Add-ons vs Joins”.
- How do I filter/sort/paginate? → Use Query All Records with filters and options.
- How do I secure endpoints? → Put them in protected API Groups and require Bearer tokens (JWE).
- How do I run long jobs? → Background Tasks; keep endpoints fast.
- How do I call external APIs? → External API Request function; map/normalize responses.
- How do I add AI? → Build Actions and Agents; call Actions from endpoints or tasks.

---

## Answering style guide for LLMs
- Start with a 1–2 sentence direct answer.
- Provide a step list or a minimal example.
- Link to the exact doc pages used.
- Mention assumptions (workspace/region/group IDs, auth settings) instead of inventing values.
- Flag plan-specific features with a “verify recency” note when relevant.

### Example answer (pattern)
```text
To list products with category and images, build an endpoint that uses Query All Records on `products`, add-ons for `category` (single) and `images` (list), and return a paginated shape. See Query All Records and Filters.

- Query All Records: https://docs.xano.com/the-function-stack/functions/database-requests/query-all-records
- Filters: https://docs.xano.com/the-function-stack/filters
```

---

## Canonical references
- Docs index: https://docs.xano.com/
- APIs in Xano: https://docs.xano.com/the-function-stack/building-with-visual-development/apis
- Data types (Function Stack): https://docs.xano.com/the-function-stack/data-types
- Database basics: https://docs.xano.com/the-database/database-basics
- Field types: https://docs.xano.com/the-database/database-basics/field-types
- Query All Records: https://docs.xano.com/the-function-stack/functions/database-requests/query-all-records
- Direct Database Query: https://docs.xano.com/the-function-stack/functions/database-requests/direct-database-query
- Filters: https://docs.xano.com/the-function-stack/filters
- External API Request: https://docs.xano.com/the-function-stack/functions/apis-and-lambdas/external-api-request
- Background Tasks: https://docs.xano.com/the-function-stack/building-with-visual-development/background-tasks
- User Authentication & User Data: https://docs.xano.com/building-backend-features/user-authentication-and-user-data
- Agents: https://docs.xano.com/ai-tools/agents
- Actions overview: https://docs.xano.com/xano-actions/what-are-actions
- Metadata API: https://docs.xano.com/xano-features/metadata-api
- Developer API (learn): https://www.xano.com/learn/Developer-API/
- Joins vs Add-ons: https://www.xano.com/learn/joins-vs-addons/
- Sort/filter Add-ons: https://www.xano.com/learn/filter-and-sort-addons/
- Pricing: https://www.xano.com/pricing/
- Increasing plan limits: https://docs.xano.com/increasing-plan-limits
---

## Glossary
- Add-on: Response-time enrichment pulling related records.
- Agent: AI-enabled, tool-using long-lived process.
- API Group: Namespace for related endpoints.
- Function Stack: Visual pipeline of operations for an endpoint.
- Metadata API: Programmatic schema/environment introspection.
- Background Task: Scheduled job for non-interactive processing.

---

## Meta
- This file is intended for LLMs and agents. It summarizes but does not replace official docs.
- When in doubt, read the linked docs and include the specific URL(s) you used.

### CRITICAL: FOR FULL DOCUMENTATION LINKS:

- [Adjust Server Performance](https://docs.xano.com/adjust-server-performance.md)
- [Agency Dashboard](https://docs.xano.com/agencies/agency-features/agency-dashboard.md)
- [Agency Profile](https://docs.xano.com/agencies/agency-features/agency-profile.md)
- [Client Invite](https://docs.xano.com/agencies/agency-features/client-invite.md)
- [Commission](https://docs.xano.com/agencies/agency-features/commission.md)
- [Private Marketplace](https://docs.xano.com/agencies/agency-features/private-marketplace.md)
- [Transfer Ownership](https://docs.xano.com/agencies/agency-features/transfer-ownership.md)
- [Xano For Agencies](https://docs.xano.com/agencies/xano-for-agencies.md)
- [Agents](https://docs.xano.com/ai-tools/agents.md): Agents are used to perform 'fuzzy logic', or perform workflows that require intricate decision making powered by an AI model
- [Templates](https://docs.xano.com/ai-tools/agents/templates.md): Agent Templates
- [MCP Builder](https://docs.xano.com/ai-tools/mcp-builder.md)
- [Connecting Clients](https://docs.xano.com/ai-tools/mcp-builder/connecting-clients.md)
- [MCP Functions](https://docs.xano.com/ai-tools/mcp-builder/mcp-functions.md)
- [Xano MCP Server](https://docs.xano.com/ai-tools/xano-mcp-server.md): Manage your Xano data using your favorite MCP client
- [API Rate Limit](https://docs.xano.com/api-rate-limit.md)
- [Key Concepts](https://docs.xano.com/before-you-begin/key-concepts.md): Get a quick primer on the key concepts and terminology that we use throughout the product and documentation to get you started quickly.
- [Navigating Xano](https://docs.xano.com/before-you-begin/navigating-xano.md)
- [Set Up A Free Xano Account](https://docs.xano.com/before-you-begin/set-up-a-free-xano-account.md): Let's make sure that you are ready to play around in Xano before continuing.
- [The Development Life Cycle](https://docs.xano.com/before-you-begin/the-development-life-cycle.md): Learn more about the fundamentals of application development and the software development life cycle.
- [Using These Docs](https://docs.xano.com/before-you-begin/using-these-docs.md)
- [Where Should I Start?](https://docs.xano.com/before-you-begin/where-should-i-start.md)
- [Chatbots](https://docs.xano.com/building-backend-features/chatbots.md)
- [Custom Report Generation](https://docs.xano.com/building-backend-features/custom-report-generation.md)
- [Emails](https://docs.xano.com/building-backend-features/emails.md)
- [Fuzzy Search](https://docs.xano.com/building-backend-features/fuzzy-search.md)
- [Messaging](https://docs.xano.com/building-backend-features/messaging.md)
- [User Authentication & User Data](https://docs.xano.com/building-backend-features/user-authentication-and-user-data.md)
- [Webhooks](https://docs.xano.com/building-backend-features/webhooks.md): Webhooks are specialized API endpoints designed to be triggered based on other events
- [CI/CD](https://docs.xano.com/ci-cd.md): Learn more about CI/CD inside of Xano
- [Compliance Center](https://docs.xano.com/enterprise/enterprise-features/compliance-center.md)
- [Deployment](https://docs.xano.com/enterprise/enterprise-features/deployment.md)
- [Instance Activity](https://docs.xano.com/enterprise/enterprise-features/instance-activity.md)
- [RBAC (Role Based Access Control)](https://docs.xano.com/enterprise/enterprise-features/rbac-role-based-access-control.md)
- [Resource Management](https://docs.xano.com/enterprise/enterprise-features/resource-management.md): BYOC (Bring your own Cloud) users can manage their available instance resources from their instance settings
- [Security Policy](https://docs.xano.com/enterprise/enterprise-features/security-policy.md)
- [Tenant Center](https://docs.xano.com/enterprise/enterprise-features/tenant-center.md)
- [Xano Link](https://docs.xano.com/enterprise/enterprise-features/xano-link.md)
- [Xano For Enterprise (Custom Plans)](https://docs.xano.com/enterprise/xano-for-enterprise.md)
- [File Storage In Xano](https://docs.xano.com/file-storage/file-storage-in-xano.md)
- [Private File Storage](https://docs.xano.com/file-storage/private-file-storage.md)
- [Frequently Asked Questions](https://docs.xano.com/frequently-asked-questions.md)
- [Increasing Plan Limits](https://docs.xano.com/increasing-plan-limits.md)
- [Welcome To Xano!](https://docs.xano.com/index.md)
- [Instance Dashboard](https://docs.xano.com/maintenance-monitoring-and-logging/instance-dashboard.md): The instance dashboard is only available to users on a paid plan.
- [Memory Usage](https://docs.xano.com/maintenance-monitoring-and-logging/instance-dashboard/memory-usage.md)
- [Request History](https://docs.xano.com/maintenance-monitoring-and-logging/request-history.md)
- [Statement Explorer](https://docs.xano.com/maintenance-monitoring-and-logging/statement-explorer.md): Use the Statement Explorer to quickly find instances of specific functions across all function stacks
- [Channel Permissions](https://docs.xano.com/realtime/channel-permissions.md)
- [Realtime In Webflow](https://docs.xano.com/realtime/realtime-in-webflow.md)
- [Realtime In Xano](https://docs.xano.com/realtime/realtime-in-xano.md)
- [Non Profits](https://docs.xano.com/special-discount-pricing/non-profits.md)
- [Students & Education](https://docs.xano.com/special-discount-pricing/students.md)
- [Branching & Merging](https://docs.xano.com/team-collaboration/branching-and-merging.md)
- [Managing Team Members](https://docs.xano.com/team-collaboration/managing-team-members.md)
- [Realtime Collaboration](https://docs.xano.com/team-collaboration/realtime-collaboration.md)
- [Docker](https://docs.xano.com/technology/docker.md)
- [Kubernetes](https://docs.xano.com/technology/kubernetes.md)
- [PostgreSQL](https://docs.xano.com/technology/postgresql.md)
- [Test Suites](https://docs.xano.com/testing-debugging/test-suites.md)
- [Testing And Debugging Function Stacks](https://docs.xano.com/testing-debugging/testing-and-debugging-function-stacks.md)
- [Unit Tests](https://docs.xano.com/testing-debugging/unit-tests.md)
- [Database Views](https://docs.xano.com/the-database/database-basics/database-views.md): Database Views are used to save filtering, sorting, and search options in your tables so that you can quickly return later.
- [Field Types](https://docs.xano.com/the-database/database-basics/field-types.md)
- [Relationships](https://docs.xano.com/the-database/database-basics/relationships.md): Database Relationships are used to define related data between one or more tables.
- [Using The Xano Database](https://docs.xano.com/the-database/database-basics/using-the-xano-database.md)
- [Designing Your Database](https://docs.xano.com/the-database/designing-your-database.md)
- [Getting Started Shortcuts](https://docs.xano.com/the-database/getting-started-shortcuts.md)
- [Additional Features](https://docs.xano.com/the-function-stack/additional-features.md)
- [Building With Visual Development](https://docs.xano.com/the-function-stack/building-with-visual-development.md)
- [APIs](https://docs.xano.com/the-function-stack/building-with-visual-development/apis.md): Learn more about building APIs using visual development in Xano
- [Background Tasks](https://docs.xano.com/the-function-stack/building-with-visual-development/background-tasks.md): Build and run workflows on a set schedule
- [Custom Functions](https://docs.xano.com/the-function-stack/building-with-visual-development/custom-functions.md): Build business logic once and reuse it in multiple places
- [Middleware](https://docs.xano.com/the-function-stack/building-with-visual-development/middleware.md)
- [Triggers](https://docs.xano.com/the-function-stack/building-with-visual-development/triggers.md)
- [Working With Data](https://docs.xano.com/the-function-stack/building-with-visual-development/working-with-data.md)
- [Data Types](https://docs.xano.com/the-function-stack/data-types.md)
- [Environment Variables](https://docs.xano.com/the-function-stack/environment-variables.md)
- [Filter Reference](https://docs.xano.com/the-function-stack/filters.md)
- [Functions Reference](https://docs.xano.com/the-function-stack/functions.md)
- [Tool Rate Limit](https://docs.xano.com/tool-rate-limit.md)
- [Error Reference](https://docs.xano.com/troubleshooting-and-support/error-reference.md)
- [Getting Help](https://docs.xano.com/troubleshooting-and-support/getting-help.md)
- [Plan Comparison](https://docs.xano.com/troubleshooting-and-support/plan-comparison.md): Information for when you're on a legacy plan and want to know how the current offerings stack up
- [Troubleshooting Performance](https://docs.xano.com/troubleshooting-and-support/troubleshooting-performance.md)
- [When A Single Workflow Feels Slow](https://docs.xano.com/troubleshooting-and-support/troubleshooting-performance/when-a-single-workflow-feels-slow.md)
- [When Everything Feels Slow](https://docs.xano.com/troubleshooting-and-support/troubleshooting-performance/when-everything-feels-slow.md)
- [What's New in Xano](https://docs.xano.com/updates.md): What's new in Xano -- Release Notes, Announcements, and Documentation Updates
- [Using AI Builders With Xano](https://docs.xano.com/using-ai-builders-with-xano.md): Get the latest on using platforms like Bolt.new, v0, and Cursor with Xano
- [AI Database Assistant](https://docs.xano.com/xano-ai/ai-database-assistant.md)
- [AI Lambda Assistant](https://docs.xano.com/xano-ai/ai-lambda-assistant.md)
- [AI SQL Assistant](https://docs.xano.com/xano-ai/ai-sql-assistant.md)
- [API Request Assistant](https://docs.xano.com/xano-ai/api-request-assistant.md)
- [Building a Backend Using AI](https://docs.xano.com/xano-ai/building-a-backend-using-ai.md)
- [Instance Settings](https://docs.xano.com/xano-features/instance-settings.md)
- [Snippets](https://docs.xano.com/xano-features/snippets.md)
- [Workspace Settings](https://docs.xano.com/xano-features/workspace-settings.md): An explanation of all available workspace settings