XanoScript for APIs

Introduction

The API primitive lets you define REST endpoints using XanoScript. Each API corresponds to an endpoint you could create in Xano’s visual builder — but expressed in code. APIs will typically:

Declare their name and HTTP verb
Accept inputs
Run one or more operations in a stack
Return a response

Anatomy

Every XanoScript API follows a predictable structure. Here’s a quick visual overview of its main building blocks — from declaration at the top to settings at the bottom.

You can find more detail about each section by continuing below.

Declaration

Every API starts with a declarative header that specifies its type, name, and HTTP verb.

XanoScript

// <what this API does>
query <api_name> verb=<VERB> {
...
}

Element	Required	Description
`query`	✅	Declares an API primitive.
`api_name`	✅	The unique path for the endpoint (e.g., `auth/signup`).
`verb`	✅	HTTP verb to use (`GET`, `POST`, `PUT`, etc.).
`description`	no	A short summary of the API. May also appear as a “//” comment above the block.

Section 1: Inputs

The input block defines the data that will be sent to the API. You can declare types, optionality, and filters:

Hover over this image to see the XanoScript version

For each input, you can:

Declare its type (text, email, password, etc.)
Mark it as optional (?)
Apply filters (filters=trim|lower)
Hide the input (when using Database Link) — The example shown below uses database link from a product table, but hides the updated_at and description fields in the inputs section. To unhide the input, just remove the corresponding override statement.

    dblink {
      table = "product"
      override = {updated_at: {hidden: true}, description: {hidden: true}}
    }

Learn more about the available input types

Section 2: Stack

The stack block contains the actual logic that will be executed when the API is called.

Hover over this image to see the XanoScript version

Each block inside stack corresponds to a function available in Xano’s visual builder:

db.get — Fetch a record from the database
precondition — Guard execution with a condition
db.add — Insert a new record into the database
security.create_auth_token — Generate an authentication token

The syntax mirrors how you’d configure these functions visually, but expressed textually. The actual behavior is the same — refer to the function’s existing docs for complete details.

Review all available functions and their XanoScript in the function reference

Section 3: Response

The response block defines what data your API returns:

Hover over this image to see the XanoScript version

The value assignment determines the JSON returned to the client.
Variables captured in the stack (e.g., $authToken) can be returned here.

Settings

API primitives support several optional settings that control authentication, tagging, caching, and version history. These settings are defined at the root level of the API block, after the input, stack, and response blocks. They affect how the endpoint behaves, how it’s documented, and how responses are cached.

Setting	Type	Required	Description
`description`	string	no	A short summary of the API. May also appear as a “//” comment above the block.
`auth`	string	no	Specifies the authentication level required for this endpoint.
`tags`	array[string]	no	A list of tags used to categorize and organize the API in your workspace.
`history`	object	no	Configures version inheritance and history behavior. This field defaults to “inherit”, which gets its values from the API group.
`cache`	object	no	Configures caching behavior for this API. See below for supported fields.

The cache block configures caching behavior for the API:

Field	Type	Description
`ttl`	number (seconds)	Time-to-live for cache entries. A value of `0` disables caching.
`input`	boolean	Whether the request body and query parameters are factored into the cache key.
`auth`	boolean	Whether authentication state (e.g., user ID) is included in the cache key.
`datasource`	boolean	Whether the datasource context is factored into the cache key.
`ip`	boolean	Whether the request IP address is included in the cache key.
`headers`	array[string]	A list of headers whose values should be included in the cache key.
`env`	array[string]	A list of environment variables whose values should be included in the cache key.

Detailed Example

Below, you’ll see a complete example of a typical signup API endpoint.

XanoScript

// Signup and retrieve an authentication token
query auth/signup verb=POST {
  input {
    text name?
    email email? filters=trim|lower
    text password?
  }

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

    precondition ($user == null) {
      error_type = "accessdenied"
      error = "This account is already in use."
    }

    db.add user {
      data = {
        created_at: "now"
        name      : $input.name
        email     : $input.email
        password  : $input.password
      }
    } as $user

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

  response = {authToken: $authToken}
}

What’s Next

Now that you understand how to define APIs in XanoScript, here are a few great next steps:

Explore the function reference

Learn about the built-in functions available in the stack to start writing more complex logic.

Try it out in VS Code

Use the XanoScript VS Code extension with Copilot to write XanoScript in your favorite IDE.

Learn about Custom Functions

They work just like APIs, but let you create reusable logic, and are a great next step when learning XanoScript.

Start

AI

References

Introduction

Anatomy

Declaration

Section 1: Inputs

Learn more about the available input types

Section 2: Stack

Review all available functions and their XanoScript in the function reference

Section 3: Response

Settings

Detailed Example

What’s Next

Explore the function reference

Try it out in VS Code

Learn about Custom Functions

​Introduction

​Anatomy

​Declaration

​Section 1: Inputs

Learn more about the available input types

​Section 2: Stack

Review all available functions and their XanoScript in the function reference

​Section 3: Response

​Settings

​Detailed Example

​What’s Next

Explore the function reference

Try it out in VS Code

Learn about Custom Functions

Introduction

Anatomy

Declaration

Section 1: Inputs

Section 2: Stack

Section 3: Response

Settings

Detailed Example

What’s Next