> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wistx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Manage budget alerts and alert preferences

Manage budget alerts and configure alert preferences for infrastructure spending.

## Get Budget Alerts

> Get all alerts for a specific budget

### Endpoint

`GET /v1/alerts/budgets/{budget_id}`

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.wistx.ai/v1/alerts/budgets/bud_abc123 \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  api_key = "YOUR_API_KEY"
  budget_id = "bud_abc123"

  response = requests.get(
      f"https://api.wistx.ai/v1/alerts/budgets/{budget_id}",
      headers={"Authorization": f"Bearer {api_key}"}
  )

  alerts = response.json()
  print(f"Found {len(alerts)} alerts")
  ```

  ```javascript JavaScript theme={null}
  const apiKey = "YOUR_API_KEY";
  const budgetId = "bud_abc123";

  const response = await fetch(
    `https://api.wistx.ai/v1/alerts/budgets/${budgetId}`,
    {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    }
  );

  const alerts = await response.json();
  console.log(`Found ${alerts.length} alerts`);
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      budgetID := "bud_abc123"
      url := fmt.Sprintf("https://api.wistx.ai/v1/alerts/budgets/%s", budgetID)

      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiKey))

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var alerts []map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&alerts)
      fmt.Printf("Found %d alerts\n", len(alerts))
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  api_key = "YOUR_API_KEY"
  budget_id = "bud_abc123"
  url = URI("https://api.wistx.ai/v1/alerts/budgets/#{budget_id}")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request["Authorization"] = "Bearer #{api_key}"

  response = http.request(request)
  alerts = JSON.parse(response.body)
  puts "Found #{alerts.length} alerts"
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = "YOUR_API_KEY";
  $budgetId = "bud_abc123";
  $url = "https://api.wistx.ai/v1/alerts/budgets/" . $budgetId;

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer " . $apiKey
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $alerts = json_decode($response, true);
  echo "Found " . count($alerts) . " alerts";
  ```

  ```java Java theme={null}
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import com.google.gson.Gson;
  import com.google.gson.JsonArray;

  public class GetBudgetAlerts {
      public static void main(String[] args) throws Exception {
          String apiKey = "YOUR_API_KEY";
          String budgetId = "bud_abc123";
          URL url = new URL("https://api.wistx.ai/v1/alerts/budgets/" + budgetId);
          
          HttpURLConnection conn = (HttpURLConnection) url.openConnection();
          conn.setRequestMethod("GET");
          conn.setRequestProperty("Authorization", "Bearer " + apiKey);
          
          BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
          StringBuilder response = new StringBuilder();
          String responseLine;
          while ((responseLine = br.readLine()) != null) {
              response.append(responseLine.trim());
          }
          
          Gson gson = new Gson();
          JsonArray alerts = gson.fromJson(response.toString(), JsonArray.class);
          System.out.println("Found " + alerts.size() + " alerts");
      }
  }
  ```
</CodeGroup>

### Path Parameters

<ParamField path="budget_id" type="string" required>
  Budget ID to get alerts for.
</ParamField>

### Response

<ResponseExample>
  ```json 200 Success theme={null}
  [
    {
      "alert_id": "alert_abc123",
      "budget_id": "bud_abc123",
      "user_id": "user_abc123",
      "alert_type": "threshold",
      "threshold_percent": 80.0,
      "current_spending_usd": 4000.0,
      "budget_limit_usd": 5000.0,
      "message": "Budget alert: 80% threshold reached",
      "severity": "warning",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "User ID not found in authentication token"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "detail": "Failed to fetch alerts: Database connection error"
  }
  ```
</ResponseExample>

## Get Alert Preferences

> Get user alert preferences

### Endpoint

`GET /v1/alerts/preferences`

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.wistx.ai/v1/alerts/preferences?budget_id=bud_abc123' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  api_key = "YOUR_API_KEY"
  response = requests.get(
      "https://api.wistx.ai/v1/alerts/preferences",
      headers={"Authorization": f"Bearer {api_key}"},
      params={"budget_id": "bud_abc123"}
  )

  preferences = response.json()
  print(f"Email alerts: {preferences.get('email_enabled')}")
  ```

  ```javascript JavaScript theme={null}
  const apiKey = "YOUR_API_KEY";
  const response = await fetch(
    "https://api.wistx.ai/v1/alerts/preferences?budget_id=bud_abc123",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    }
  );

  const preferences = await response.json();
  console.log(`Email alerts: ${preferences.email_enabled}`);
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
      "net/url"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      baseURL := "https://api.wistx.ai/v1/alerts/preferences"
      
      params := url.Values{}
      params.Add("budget_id", "bud_abc123")
      fullURL := baseURL + "?" + params.Encode()

      req, _ := http.NewRequest("GET", fullURL, nil)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiKey))

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var preferences map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&preferences)
      fmt.Printf("Email alerts: %v\n", preferences["email_enabled"])
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  api_key = "YOUR_API_KEY"
  url = URI("https://api.wistx.ai/v1/alerts/preferences?budget_id=bud_abc123")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request["Authorization"] = "Bearer #{api_key}"

  response = http.request(request)
  preferences = JSON.parse(response.body)
  puts "Email alerts: #{preferences['email_enabled']}"
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = "YOUR_API_KEY";
  $url = "https://api.wistx.ai/v1/alerts/preferences?budget_id=bud_abc123";

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer " . $apiKey
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $preferences = json_decode($response, true);
  echo "Email alerts: " . ($preferences['email_enabled'] ? 'true' : 'false');
  ```

  ```java Java theme={null}
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import com.google.gson.Gson;
  import com.google.gson.JsonObject;

  public class GetAlertPreferences {
      public static void main(String[] args) throws Exception {
          String apiKey = "YOUR_API_KEY";
          URL url = new URL("https://api.wistx.ai/v1/alerts/preferences?budget_id=bud_abc123");
          
          HttpURLConnection conn = (HttpURLConnection) url.openConnection();
          conn.setRequestMethod("GET");
          conn.setRequestProperty("Authorization", "Bearer " + apiKey);
          
          BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
          StringBuilder response = new StringBuilder();
          String responseLine;
          while ((responseLine = br.readLine()) != null) {
              response.append(responseLine.trim());
          }
          
          Gson gson = new Gson();
          JsonObject preferences = gson.fromJson(response.toString(), JsonObject.class);
          System.out.println("Email alerts: " + preferences.get("email_enabled"));
      }
  }
  ```
</CodeGroup>

### Query Parameters

<ParamField query="budget_id" type="string">
  Budget ID (optional, for budget-specific preferences). If not provided, returns global preferences.
</ParamField>

### Response

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "user_id": "user_abc123",
    "budget_id": "bud_abc123",
    "email_enabled": true,
    "webhook_url": null,
    "alert_thresholds": {
      "warning": 80.0,
      "critical": 95.0
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "User ID not found in authentication token"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "detail": "Failed to retrieve preferences"
  }
  ```
</ResponseExample>

## Update Alert Preferences

> Update user alert preferences

### Endpoint

`POST /v1/alerts/preferences`

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.wistx.ai/v1/alerts/preferences \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "user_id": "user_abc123",
      "budget_id": "bud_abc123",
      "email_enabled": true,
      "webhook_url": "https://example.com/webhook",
      "alert_thresholds": {
        "warning": 80.0,
        "critical": 95.0
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  api_key = "YOUR_API_KEY"
  response = requests.post(
      "https://api.wistx.ai/v1/alerts/preferences",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={
          "user_id": "user_abc123",
          "budget_id": "bud_abc123",
          "email_enabled": True,
          "webhook_url": "https://example.com/webhook",
          "alert_thresholds": {
              "warning": 80.0,
              "critical": 95.0
          }
      }
  )

  preferences = response.json()
  print(f"Preferences updated: {preferences['email_enabled']}")
  ```

  ```javascript JavaScript theme={null}
  const apiKey = "YOUR_API_KEY";
  const response = await fetch("https://api.wistx.ai/v1/alerts/preferences", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      user_id: "user_abc123",
      budget_id: "bud_abc123",
      email_enabled: true,
      webhook_url: "https://example.com/webhook",
      alert_thresholds: {
        warning: 80.0,
        critical: 95.0
      }
    })
  });

  const preferences = await response.json();
  console.log(`Preferences updated: ${preferences.email_enabled}`);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      url := "https://api.wistx.ai/v1/alerts/preferences"

      payload := map[string]interface{}{
          "user_id": "user_abc123",
          "budget_id": "bud_abc123",
          "email_enabled": true,
          "webhook_url": "https://example.com/webhook",
          "alert_thresholds": map[string]float64{
              "warning": 80.0,
              "critical": 95.0,
          },
      }

      jsonData, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiKey))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var preferences map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&preferences)
      fmt.Printf("Preferences updated: %v\n", preferences["email_enabled"])
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  api_key = "YOUR_API_KEY"
  url = URI("https://api.wistx.ai/v1/alerts/preferences")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Authorization"] = "Bearer #{api_key}"
  request["Content-Type"] = "application/json"
  request.body = {
    user_id: "user_abc123",
    budget_id: "bud_abc123",
    email_enabled: true,
    webhook_url: "https://example.com/webhook",
    alert_thresholds: {
      warning: 80.0,
      critical: 95.0
    }
  }.to_json

  response = http.request(request)
  preferences = JSON.parse(response.body)
  puts "Preferences updated: #{preferences['email_enabled']}"
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = "YOUR_API_KEY";
  $url = "https://api.wistx.ai/v1/alerts/preferences";

  $data = [
      "user_id" => "user_abc123",
      "budget_id" => "bud_abc123",
      "email_enabled" => true,
      "webhook_url" => "https://example.com/webhook",
      "alert_thresholds" => [
          "warning" => 80.0,
          "critical" => 95.0
      ]
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer " . $apiKey,
      "Content-Type: application/json"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $preferences = json_decode($response, true);
  echo "Preferences updated: " . ($preferences['email_enabled'] ? 'true' : 'false');
  ```

  ```java Java theme={null}
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.io.OutputStream;
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import com.google.gson.Gson;
  import com.google.gson.JsonObject;

  public class UpdateAlertPreferences {
      public static void main(String[] args) throws Exception {
          String apiKey = "YOUR_API_KEY";
          URL url = new URL("https://api.wistx.ai/v1/alerts/preferences");
          
          HttpURLConnection conn = (HttpURLConnection) url.openConnection();
          conn.setRequestMethod("POST");
          conn.setRequestProperty("Authorization", "Bearer " + apiKey);
          conn.setRequestProperty("Content-Type", "application/json");
          conn.setDoOutput(true);
          
          JsonObject alertThresholds = new JsonObject();
          alertThresholds.addProperty("warning", 80.0);
          alertThresholds.addProperty("critical", 95.0);
          
          JsonObject payload = new JsonObject();
          payload.addProperty("user_id", "user_abc123");
          payload.addProperty("budget_id", "bud_abc123");
          payload.addProperty("email_enabled", true);
          payload.addProperty("webhook_url", "https://example.com/webhook");
          payload.add("alert_thresholds", alertThresholds);
          
          Gson gson = new Gson();
          try (OutputStream os = conn.getOutputStream()) {
              byte[] input = gson.toJson(payload).getBytes("utf-8");
              os.write(input, 0, input.length);
          }
          
          BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
          StringBuilder response = new StringBuilder();
          String responseLine;
          while ((responseLine = br.readLine()) != null) {
              response.append(responseLine.trim());
          }
          System.out.println(response.toString());
      }
  }
  ```
</CodeGroup>

### Request Parameters

<ParamField body="user_id" type="string" required>
  User ID (must match authenticated user).
</ParamField>

<ParamField body="budget_id" type="string">
  Budget ID for budget-specific preferences. If not provided, sets global preferences.
</ParamField>

<ParamField body="email_enabled" type="boolean">
  Enable email alerts.

  **Default:** `true`
</ParamField>

<ParamField body="webhook_url" type="string">
  Webhook URL for alert notifications (optional).
</ParamField>

<ParamField body="alert_thresholds" type="object">
  Custom alert thresholds.

  **Properties:**

  * `warning` - Warning threshold percentage
  * `critical` - Critical threshold percentage
</ParamField>

### Response

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "user_id": "user_abc123",
    "budget_id": "bud_abc123",
    "email_enabled": true,
    "webhook_url": "https://example.com/webhook",
    "alert_thresholds": {
      "warning": 80.0,
      "critical": 95.0
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "User ID not found in authentication token"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "detail": "Cannot update preferences for another user"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "detail": "Failed to update preferences"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Infrastructure Budget](/api-reference/budget) - Manage infrastructure budgets


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.