Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trellis.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Authorization
string
required
Bearer token obtained from the authenticate endpoint.
​
title
string
required
Display title for the query.
​
prompt
string
required
The natural language instruction that describes what this query does. Passed to the AI agent when the query is invoked via chat.
​
sql
string
The SQL to execute when this query is invoked. Use {{param_name}} placeholders for values that should be supplied at runtime (e.g. WHERE year = {{year}}). The server automatically extracts these into the parameters field on the response. If omitted, the query is prompt-only — the prompt is passed directly to the AI agent without pre-executing any SQL.
​
description
string
Optional human-readable description of what the query does.
​
keywords
string[]
Optional list of keywords for automatic semantic matching. When a chat message’s content matches these terms, this query may be surfaced automatically.

​
Response

Returns the created saved query object.
​
id
string
required
Unique identifier for the newly created query.
​
organization_id
string
required
Organization the query belongs to.
​
title
string
required
Display title for the query.
​
description
string
Description of the query, if provided.
​
prompt
string
required
The natural language instruction for this query.
​
sql
string
The SQL associated with this query, or null for prompt-only queries.
​
keywords
string[]
Keywords for semantic matching, if provided.
​
parameters
string[]
Names of all {{param_name}} placeholders detected in sql, auto-extracted by the server. This field is read-only.
​
last_updated_by
string
required
Member ID of the user who created this query.
​
last_updated_by_name
string
Display name of the user who created this query.
​
created_at
string
required
ISO 8601 timestamp when the query was created.
​
updated_at
string
required
ISO 8601 timestamp when the query was created.
curl -X POST https://api.trellis.sh/v1/queries \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Top Customers",
    "prompt": "Who are our top customers by total spend?",
    "sql": "SELECT customer_id, SUM(amount) AS total_spend FROM orders GROUP BY customer_id ORDER BY total_spend DESC LIMIT {{limit}}",
    "description": "Returns the top N customers ranked by total spend",
    "keywords": ["customers", "spend", "top"]
  }'

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "organization_id": "org_abc123",
  "title": "Top Customers",
  "description": "Returns the top N customers ranked by total spend",
  "prompt": "Who are our top customers by total spend?",
  "sql": "SELECT customer_id, SUM(amount) AS total_spend FROM orders GROUP BY customer_id ORDER BY total_spend DESC LIMIT {{limit}}",
  "keywords": ["customers", "spend", "top"],
  "parameters": ["limit"],
  "last_updated_by": "member_xyz789",
  "last_updated_by_name": "Jane Smith",
  "created_at": "2025-01-11T10:00:00Z",
  "updated_at": "2025-01-11T10:00:00Z"
}