> ## 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.

# Update Saved Query

> Update an existing saved query

Partially update a saved query. Only include the fields you want to change. When `sql` is updated, `parameters` is automatically re-extracted from the new SQL.

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the authenticate endpoint.
</ParamField>

<ParamField path="query_id" type="string" required>
  Unique identifier of the saved query to update.
</ParamField>

<ParamField body="title" type="string">
  New display title for the query.
</ParamField>

<ParamField body="prompt" type="string">
  New natural language instruction for the query.
</ParamField>

<ParamField body="sql" type="string">
  New SQL to associate with the query. Use `{{param_name}}` placeholders for values that should be supplied at runtime. Updating this field automatically re-extracts `parameters`.
</ParamField>

<ParamField body="description" type="string">
  New description for the query.
</ParamField>

<ParamField body="keywords" type="string[]">
  New list of keywords for semantic matching. Pass an empty array to remove all keywords.
</ParamField>

## Response

Returns the updated saved query object.

<ResponseField name="id" type="string" required>
  Unique identifier for the query.
</ResponseField>

<ResponseField name="organization_id" type="string" required>
  Organization the query belongs to.
</ResponseField>

<ResponseField name="title" type="string" required>
  Updated display title.
</ResponseField>

<ResponseField name="description" type="string">
  Updated description.
</ResponseField>

<ResponseField name="prompt" type="string" required>
  Updated natural language instruction.
</ResponseField>

<ResponseField name="sql" type="string">
  The current SQL for this query, or `null` for prompt-only queries.
</ResponseField>

<ResponseField name="keywords" type="string[]">
  Updated keywords list.
</ResponseField>

<ResponseField name="parameters" type="string[]">
  Re-extracted `{{param_name}}` placeholder names from the current `sql`. Updated automatically whenever `sql` changes.
</ResponseField>

<ResponseField name="last_updated_by" type="string" required>
  Member ID of the user who made this update.
</ResponseField>

<ResponseField name="last_updated_by_name" type="string">
  Display name of the user who made this update.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the query was originally created.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp of this update.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X PATCH https://api.trellis.sh/v1/queries/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Top Customers by Region",
      "prompt": "Who are our top customers by total spend in {{region}}?",
      "sql": "SELECT customer_id, SUM(amount) AS total_spend FROM orders WHERE region = {{region}} GROUP BY customer_id ORDER BY total_spend DESC LIMIT {{limit}}"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.patch(
      "https://api.trellis.sh/v1/queries/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Content-Type": "application/json"
      },
      json={
          "title": "Top Customers by Region",
          "prompt": "Who are our top customers by total spend in {{region}}?",
          "sql": "SELECT customer_id, SUM(amount) AS total_spend FROM orders WHERE region = {{region}} GROUP BY customer_id ORDER BY total_spend DESC LIMIT {{limit}}"
      }
  )
  updated_query = response.json()
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/queries/b2c3d4e5-f6a7-8901-bcde-f12345678901", {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Top Customers by Region",
      prompt: "Who are our top customers by total spend in {{region}}?",
      sql: "SELECT customer_id, SUM(amount) AS total_spend FROM orders WHERE region = {{region}} GROUP BY customer_id ORDER BY total_spend DESC LIMIT {{limit}}",
    }),
  });
  const updatedQuery = await response.json();
  ```
</RequestExample>

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

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Query not found"
  }
  ```
</ResponseExample>