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

# Create Budget

> Create a new infrastructure budget for tracking spending

> Create a new infrastructure budget for tracking spending

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.wistx.ai/v1/budgets \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Production Infrastructure Budget",
      "description": "Monthly budget for production AWS infrastructure",
      "scope": {
        "type": "cloud_provider",
        "cloud_provider": "aws"
      },
      "monthly_limit_usd": 5000.0,
      "alert_threshold_percent": 80.0,
      "critical_threshold_percent": 95.0,
      "enforcement_mode": "alert"
    }'
  ```

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

  api_key = "YOUR_API_KEY"
  url = "https://api.wistx.ai/v1/budgets"

  response = requests.post(
      url,
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={
          "name": "Production Infrastructure Budget",
          "description": "Monthly budget for production AWS infrastructure",
          "scope": {
              "type": "cloud_provider",
              "cloud_provider": "aws"
          },
          "monthly_limit_usd": 5000.0,
          "alert_threshold_percent": 80.0,
          "critical_threshold_percent": 95.0,
          "enforcement_mode": "alert"
      }
  )

  budget = response.json()
  print(f"Budget created: {budget['budget_id']}")
  ```

  ```javascript JavaScript theme={null}
  const apiKey = "YOUR_API_KEY";
  const url = "https://api.wistx.ai/v1/budgets";

  const response = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "Production Infrastructure Budget",
      description: "Monthly budget for production AWS infrastructure",
      scope: {
        type: "cloud_provider",
        cloud_provider: "aws"
      },
      monthly_limit_usd: 5000.0,
      alert_threshold_percent: 80.0,
      critical_threshold_percent: 95.0,
      enforcement_mode: "alert"
    })
  });

  const budget = await response.json();
  console.log(`Budget created: ${budget.budget_id}`);
  ```

  ```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/budgets"

      payload := map[string]interface{}{
          "name": "Production Infrastructure Budget",
          "description": "Monthly budget for production AWS infrastructure",
          "scope": map[string]interface{}{
              "type": "cloud_provider",
              "cloud_provider": "aws",
          },
          "monthly_limit_usd": 5000.0,
          "alert_threshold_percent": 80.0,
          "critical_threshold_percent": 95.0,
          "enforcement_mode": "alert",
      }

      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 budget map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&budget)
      fmt.Printf("Budget created: %v\n", budget["budget_id"])
  }
  ```

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

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

  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 = {
    name: "Production Infrastructure Budget",
    description: "Monthly budget for production AWS infrastructure",
    scope: {
      type: "cloud_provider",
      cloud_provider: "aws"
    },
    monthly_limit_usd: 5000.0,
    alert_threshold_percent: 80.0,
    critical_threshold_percent: 95.0,
    enforcement_mode: "alert"
  }.to_json

  response = http.request(request)
  budget = JSON.parse(response.body)
  puts "Budget created: #{budget['budget_id']}"
  ```

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

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

  $data = [
      "name" => "Production Infrastructure Budget",
      "description" => "Monthly budget for production AWS infrastructure",
      "scope" => [
          "type" => "cloud_provider",
          "cloud_provider" => "aws"
      ],
      "monthly_limit_usd" => 5000.0,
      "alert_threshold_percent" => 80.0,
      "critical_threshold_percent" => 95.0,
      "enforcement_mode" => "alert"
  ];

  $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);

  $budget = json_decode($response, true);
  echo "Budget created: " . $budget['budget_id'];
  ```

  ```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 CreateBudget {
      public static void main(String[] args) throws Exception {
          String apiKey = "YOUR_API_KEY";
          URL url = new URL("https://api.wistx.ai/v1/budgets");
          
          HttpURLConnection conn = (HttpURLConnection) url.openConnection();
          conn.setRequestMethod("POST");
          conn.setRequestProperty("Authorization", "Bearer " + apiKey);
          conn.setRequestProperty("Content-Type", "application/json");
          conn.setDoOutput(true);
          
          JsonObject scope = new JsonObject();
          scope.addProperty("type", "cloud_provider");
          scope.addProperty("cloud_provider", "aws");
          
          JsonObject payload = new JsonObject();
          payload.addProperty("name", "Production Infrastructure Budget");
          payload.addProperty("description", "Monthly budget for production AWS infrastructure");
          payload.add("scope", scope);
          payload.addProperty("monthly_limit_usd", 5000.0);
          payload.addProperty("alert_threshold_percent", 80.0);
          payload.addProperty("critical_threshold_percent", 95.0);
          payload.addProperty("enforcement_mode", "alert");
          
          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="name" type="string" required>
  Budget name.

  **Minimum:** 1 character\
  **Maximum:** 200 characters
</ParamField>

<ParamField body="description" type="string">
  Budget description.

  **Maximum:** 1000 characters
</ParamField>

<ParamField body="scope" type="object" required>
  Budget scope definition.

  **Scope Types:**

  * `overall` - Track all infrastructure spending
  * `cloud_provider` - Track spending for a specific cloud provider (requires `cloud_provider` field)
  * `environment` - Track spending for a specific environment (requires `environment_name` field)

  **Examples:**

  * Overall: `{"type": "overall"}`
  * Cloud Provider: `{"type": "cloud_provider", "cloud_provider": "aws"}`
  * Environment: `{"type": "environment", "environment_name": "production"}`
  * Combined: `{"type": "environment", "cloud_provider": "aws", "environment_name": "production"}`
</ParamField>

<ParamField body="monthly_limit_usd" type="number" required>
  Monthly budget limit in USD.

  **Minimum:** Greater than 0
</ParamField>

<ParamField body="alert_threshold_percent" type="number">
  Alert threshold percentage. Alerts are sent when spending reaches this percentage of the budget.

  **Default:** `80.0`\
  **Minimum:** 0\
  **Maximum:** 100
</ParamField>

<ParamField body="critical_threshold_percent" type="number">
  Critical alert threshold percentage. Critical alerts are sent when spending reaches this percentage.

  **Default:** `95.0`\
  **Minimum:** 0\
  **Maximum:** 100
</ParamField>

<ParamField body="enforcement_mode" type="string">
  Budget enforcement mode.

  **Options:** `alert`, `warn`, `block`\
  **Default:** `alert`
</ParamField>

<ParamField body="organization_id" type="string">
  Organization ID if budget is shared within an organization.
</ParamField>

## Response

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "budget_id": "bud_abc123",
    "name": "Production Infrastructure Budget",
    "description": "Monthly budget for production AWS infrastructure",
    "scope": {
      "type": "cloud_provider",
      "cloud_provider": "aws"
    },
    "monthly_limit_usd": 5000.0,
    "alert_threshold_percent": 80.0,
    "critical_threshold_percent": 95.0,
    "status": "active",
    "enforcement_mode": "alert",
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-02-01T00:00:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "cloud_provider is required for cloud_provider scope",
      "details": null
    },
    "metadata": {
      "request_id": "req_abc123",
      "timestamp": 1704067200.0
    }
  }
  ```

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

  ```json 500 Internal Server Error theme={null}
  {
    "error": {
      "code": "BUDGET_CREATION_ERROR",
      "message": "Failed to create budget",
      "details": null
    },
    "metadata": {
      "request_id": "req_abc123",
      "timestamp": 1704067200.0
    }
  }
  ```
</ResponseExample>

## Related Endpoints

* [List Budgets](/api-reference/budget/list-budgets) - List all budgets
* [Get Budget](/api-reference/budget/get-budget) - Get budget details
* [Get Budget Status](/api-reference/budget/budget-status) - Get budget status and spending


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