@xano/developer-mcp 1.0.0

package/api_docs/api_group.md

@@ -0,0 +1,236 @@
+# API Group & Endpoints
+
+API Groups are containers for related API endpoints. Each API group has its own base URL and can contain multiple API endpoints.
+
+## API Group Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/apigroup` | List API groups |
+| GET | `/workspace/{workspace_id}/apigroup/{apigroup_id}` | Get API group |
+| POST | `/workspace/{workspace_id}/apigroup` | Create API group |
+| PUT | `/workspace/{workspace_id}/apigroup/{apigroup_id}` | Update API group |
+| DELETE | `/workspace/{workspace_id}/apigroup/{apigroup_id}` | Delete API group |
+| PUT | `/workspace/{workspace_id}/apigroup/{apigroup_id}/security` | Update security |
+| GET | `/workspace/{workspace_id}/apigroup/{apigroup_id}/openapi` | Get OpenAPI spec |
+
+## API Endpoint Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api` | List endpoints |
+| GET | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}` | Get endpoint |
+| POST | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api` | Create endpoint |
+| PUT | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}` | Update endpoint |
+| DELETE | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}` | Delete endpoint |
+| PUT | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}/security` | Update security |
+| GET | `/workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}/openapi` | Get OpenAPI spec |
+
+---
+
+## List API Groups
+
+```
+GET /workspace/{workspace_id}/apigroup
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort field |
+| `order` | enum | "desc" | Sort order |
+| `middleware` | bool | true | Include middleware info |
+
+---
+
+## Create API Group
+
+```
+POST /workspace/{workspace_id}/apigroup
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+```xanoscript
+api_group foo {
+  canonical = "custom"
+  swagger = {active: true}
+}
+```
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+- `middleware` (bool): Include middleware in response
+
+---
+
+## Update API Group
+
+```
+PUT /workspace/{workspace_id}/apigroup/{apigroup_id}
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete API Group
+
+```
+DELETE /workspace/{workspace_id}/apigroup/{apigroup_id}
+```
+
+Deletes the API group and all its endpoints. Cannot be undone.
+
+---
+
+## Update API Group Security
+
+```
+PUT /workspace/{workspace_id}/apigroup/{apigroup_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |
+| `canonical` | text | Yes | Canonical URL path |
+
+---
+
+## Get API Group OpenAPI Spec
+
+```
+GET /workspace/{workspace_id}/apigroup/{apigroup_id}/openapi
+```
+
+Returns OpenAPI specification as JSON.
+
+---
+
+# API Endpoints
+
+## List API Endpoints
+
+```
+GET /workspace/{workspace_id}/apigroup/{apigroup_id}/api
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort field |
+| `order` | enum | "desc" | Sort order |
+
+---
+
+## Create API Endpoint
+
+```
+POST /workspace/{workspace_id}/apigroup/{apigroup_id}/api
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+### XanoScript API Endpoint Syntax
+
+```xanoscript
+query foo verb=GET {
+  input {
+    int score
+  }
+
+  stack {
+    var $x1 {
+      value = $input.score + 1
+    }
+  }
+
+  response = $x1
+}
+```
+
+### HTTP Verbs
+Use `verb=` to specify: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
+
+### Input Section
+Define request parameters:
+
+```xanoscript
+input {
+  int required_param
+  text optional_param?
+  bool param_with_default? default = true
+}
+```
+
+### Stack Section
+The API logic using XanoScript:
+
+```xanoscript
+stack {
+  // Variable assignment
+  var $result {
+    value = $input.score * 2
+  }
+
+  // Database queries
+  db.query user {
+    where = $db.user.id == $input.user_id
+    return = {type: "single"}
+  }
+
+  // Conditional logic
+  if $input.score > 10 {
+    var $bonus { value = 100 }
+  }
+}
+```
+
+### Response
+Define what the endpoint returns:
+
+```xanoscript
+response = $result
+```
+
+---
+
+## Update API Endpoint
+
+```
+PUT /workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+
+**Content-Type:** `text/x-xanoscript`
+
+---
+
+## Delete API Endpoint
+
+```
+DELETE /workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}
+```
+
+---
+
+## Update API Endpoint Security
+
+```
+PUT /workspace/{workspace_id}/apigroup/{apigroup_id}/api/{api_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |

package/api_docs/authentication.md

@@ -0,0 +1,68 @@
+# Authentication API
+
+The Headless API requires authentication for all endpoints. This document covers the authentication endpoint.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/auth/me` | Get current user info |
+
+---
+
+## Get Current User
+
+```
+GET /auth/me
+```
+
+Retrieve information about the authenticated user.
+
+**Response Example:**
+```json
+{
+  "id": 123,
+  "name": "User Name",
+  "email": "user@example.com",
+  "extras": {
+    "instance": {
+      "membership": {
+        "role": "admin",
+        "workspace": {
+          "id": [1, 2, 3]
+        }
+      }
+    }
+  }
+}
+```
+
+**Response Fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | int | User's unique identifier |
+| `name` | text | User's display name |
+| `email` | text | User's email address |
+| `extras` | object | Additional authentication context |
+
+### Extras Object
+
+The `extras` object contains instance membership information:
+
+| Path | Description |
+|------|-------------|
+| `extras.instance.membership.role` | User's role |
+| `extras.instance.membership.workspace.id` | Accessible workspace IDs (for free tier) |
+
+### User Roles
+
+| Role | Description |
+|------|-------------|
+| `explore` | Free tier - limited workspace access |
+| `admin` | Full access to all workspaces |
+
+### Notes
+
+- The `workspace.id` array is used for free tier users to restrict access
+- Paid users can access all workspaces not in the disabled list
+- The role determines what operations the user can perform

package/api_docs/file.md

@@ -0,0 +1,190 @@
+# File & Static Hosting API
+
+File management endpoints allow you to upload, list, and delete files in a workspace. Static hosting allows you to deploy static websites.
+
+## File Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/file` | List files |
+| POST | `/workspace/{workspace_id}/file` | Upload file |
+| DELETE | `/workspace/{workspace_id}/file/{file_id}` | Delete file |
+| DELETE | `/workspace/{workspace_id}/file/bulk_delete` | Bulk delete files |
+
+## Static Host Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/static_host` | List static hosts |
+| GET | `/workspace/{workspace_id}/static_host/{static_host}/build` | List builds |
+| POST | `/workspace/{workspace_id}/static_host/{static_host}/build` | Create build |
+| GET | `/workspace/{workspace_id}/static_host/{static_host}/build/{build_id}` | Get build |
+| POST | `/workspace/{workspace_id}/static_host/{static_host}/build/{build_id}/env` | Deploy to environment |
+| DELETE | `/workspace/{workspace_id}/static_host/{static_host}/build/{build_id}` | Delete build |
+
+---
+
+# Files
+
+## List Files
+
+```
+GET /workspace/{workspace_id}/file
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search by filename or MIME type |
+| `access` | enum | "public" | Access level: "public", "private" |
+| `sort` | enum | "created_at" | Sort: "created_at", "name", "size", "mime" |
+| `order` | enum | "desc" | Sort order |
+
+**Response Fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | int | File unique identifier |
+| `name` | text | Original filename |
+| `size` | int | File size in bytes |
+| `mime` | text | MIME type |
+| `path` | text | Public URL path |
+| `access` | enum | Access level |
+| `created_at` | timestamp | Upload timestamp |
+
+---
+
+## Upload File
+
+```
+POST /workspace/{workspace_id}/file
+```
+
+**Content-Type:** `multipart/form-data`
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `content` | file | Yes | - | File to upload |
+| `type` | enum | No | "" | Type hint: "image", "video", "audio" |
+| `access` | enum | No | "public" | Access: "public", "private" |
+
+**Notes:**
+- Free tier users are restricted to image uploads only
+- File size limits may apply based on plan
+
+---
+
+## Delete File
+
+```
+DELETE /workspace/{workspace_id}/file/{file_id}
+```
+
+**Warning:** Cannot be undone.
+
+---
+
+## Bulk Delete Files
+
+```
+DELETE /workspace/{workspace_id}/file/bulk_delete
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids[]` | int[] | Yes | Array of file IDs to delete |
+
+**Warning:** Cannot be undone.
+
+---
+
+# Static Hosting
+
+## List Static Hosts
+
+```
+GET /workspace/{workspace_id}/static_host
+```
+
+**Query Parameters:**
+- `page` (int, default: 1): Page number
+
+---
+
+## List Builds
+
+```
+GET /workspace/{workspace_id}/static_host/{static_host}/build
+```
+
+**Path Parameters:**
+- `static_host` (text): Static host name
+
+**Query Parameters:**
+- `page` (int, default: 1): Page number
+
+---
+
+## Create Build
+
+```
+POST /workspace/{workspace_id}/static_host/{static_host}/build
+```
+
+Upload a zip file to create a new build.
+
+**Content-Type:** `multipart/form-data`
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file` | file | Yes | - | Zip archive of static site |
+| `name` | text | Yes | - | Build name/version |
+| `description` | text | No | "" | Build description |
+
+**Response:**
+Returns created build object with dev environment URL.
+
+**Notes:**
+- New builds are automatically deployed to `dev` environment
+- Upload a zip file containing your static site files
+- If `static_host` is "default" and doesn't exist, it will be created
+
+---
+
+## Get Build
+
+```
+GET /workspace/{workspace_id}/static_host/{static_host}/build/{build_id}
+```
+
+---
+
+## Deploy Build to Environment
+
+```
+POST /workspace/{workspace_id}/static_host/{static_host}/build/{build_id}/env
+```
+
+Deploy a build to a specific environment.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `env` | enum | Yes | Environment: "prod", "dev" |
+
+**Response:**
+Returns the environment URL for the deployed build.
+
+---
+
+## Delete Build
+
+```
+DELETE /workspace/{workspace_id}/static_host/{static_host}/build/{build_id}
+```
+
+**Warning:** Cannot be undone.

package/api_docs/function.md

@@ -0,0 +1,217 @@
+# Function API
+
+Functions are reusable code blocks that can be called from API endpoints, tasks, triggers, and other functions. They are defined using XanoScript.
+
+## Endpoints Overview
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/workspace/{workspace_id}/function` | List functions |
+| GET | `/workspace/{workspace_id}/function/{function_id}` | Get function |
+| POST | `/workspace/{workspace_id}/function` | Create function |
+| PUT | `/workspace/{workspace_id}/function/{function_id}` | Update function |
+| DELETE | `/workspace/{workspace_id}/function/{function_id}` | Delete function |
+| PUT | `/workspace/{workspace_id}/function/{function_id}/security` | Update security |
+
+---
+
+## List Functions
+
+```
+GET /workspace/{workspace_id}/function
+```
+
+**Query Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `branch` | text | "" | Branch label |
+| `page` | int | 1 | Page number |
+| `per_page` | int | 50 | Items per page (1-10000) |
+| `search` | text | "" | Search filter |
+| `sort` | enum | "created_at" | Sort: "created_at", "updated_at", "name" |
+| `order` | enum | "desc" | Sort order |
+
+---
+
+## Get Function
+
+```
+GET /workspace/{workspace_id}/function/{function_id}
+```
+
+Returns function definition including XanoScript.
+
+---
+
+## Create Function
+
+```
+POST /workspace/{workspace_id}/function
+```
+
+**Content-Type:** `text/x-xanoscript`
+
+**Query Parameters:**
+- `branch` (text): Target branch label
+
+### XanoScript Function Syntax
+
+```xanoscript
+function foo {
+  input {
+    int score
+  }
+
+  stack {
+    var $x1 {
+      value = $input.score + 1
+    }
+  }
+
+  response = $x1
+}
+```
+
+### Input Section
+
+Define input parameters:
+
+```xanoscript
+input {
+  int required_param
+  text optional_param?
+  bool param_with_default? default = true
+}
+```
+
+| Modifier | Syntax | Description |
+|----------|--------|-------------|
+| Required | `type name` | Parameter is required |
+| Optional | `type name?` | Parameter is nullable |
+| Default | `default = value` | Provides default value |
+
+### Stack Section
+
+The function logic using XanoScript statements:
+
+```xanoscript
+stack {
+  // Variable assignment
+  var $result {
+    value = $input.score * 2
+  }
+
+  // Database queries
+  db.query user {
+    where = $db.user.id == $input.user_id
+    return = {type: "single"}
+  }
+
+  // Conditional logic
+  if $input.score > 10 {
+    var $bonus {
+      value = 100
+    }
+  }
+
+  // Loops
+  foreach $items as $item {
+    // Process each item
+  }
+}
+```
+
+### Response
+
+Define what the function returns:
+
+```xanoscript
+response = $result
+```
+
+### Complete Example
+
+```xanoscript
+function calculate_discount {
+  input {
+    float price
+    int quantity
+    text coupon_code?
+  }
+
+  stack {
+    var $base_discount {
+      value = 0
+    }
+
+    // Volume discount
+    if $input.quantity > 10 {
+      var $base_discount {
+        value = 0.1
+      }
+    }
+
+    // Coupon lookup
+    if $input.coupon_code != null {
+      db.query coupon {
+        where = $db.coupon.code == $input.coupon_code
+        return = {type: "single"}
+      }
+
+      if $coupon != null {
+        var $base_discount {
+          value = $base_discount + $coupon.discount
+        }
+      }
+    }
+
+    var $final_price {
+      value = $input.price * $input.quantity * (1 - $base_discount)
+    }
+  }
+
+  response = {
+    original: $input.price * $input.quantity,
+    discount: $base_discount,
+    final: $final_price
+  }
+}
+```
+
+---
+
+## Update Function
+
+```
+PUT /workspace/{workspace_id}/function/{function_id}
+```
+
+**Query Parameters:**
+- `publish` (bool, default: true): Publish changes immediately
+
+**Content-Type:** `text/x-xanoscript`
+
+Send complete function definition.
+
+---
+
+## Delete Function
+
+```
+DELETE /workspace/{workspace_id}/function/{function_id}
+```
+
+**Warning:** This action cannot be undone. Any code calling this function will fail.
+
+---
+
+## Update Function Security
+
+```
+PUT /workspace/{workspace_id}/function/{function_id}/security
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | text | Yes | New security GUID |