Update Budget thresholds or state

curl --request PATCH \
  --url https://api.checkfu.com/v1/budgets/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "expected_version": 1,
  "soft_threshold": {
    "limit": 1,
    "action": "notify"
  }
}
'

import requests

url = "https://api.checkfu.com/v1/budgets/{id}"

payload = {
    "expected_version": 1,
    "soft_threshold": {
        "limit": 1,
        "action": "notify"
    }
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({expected_version: 1, soft_threshold: {limit: 1, action: 'notify'}})
};

fetch('https://api.checkfu.com/v1/budgets/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/budgets/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'expected_version' => 1,
    'soft_threshold' => [
        'limit' => 1,
        'action' => 'notify'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/budgets/{id}"

	payload := strings.NewReader("{\n  \"expected_version\": 1,\n  \"soft_threshold\": {\n    \"limit\": 1,\n    \"action\": \"notify\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.checkfu.com/v1/budgets/{id}")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expected_version\": 1,\n  \"soft_threshold\": {\n    \"limit\": 1,\n    \"action\": \"notify\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/budgets/{id}")

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

request = Net::HTTP::Patch.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expected_version\": 1,\n  \"soft_threshold\": {\n    \"limit\": 1,\n    \"action\": \"notify\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "workspace_id": "<string>",
  "scope": {
    "kind": "workspace",
    "agent_definition_id": "<unknown>",
    "principal_id": "<unknown>",
    "surface_scope_id": "<unknown>",
    "automation_id": "<unknown>",
    "session_id": "<unknown>"
  },
  "metric": "model_tokens",
  "window": {
    "kind": "rolling",
    "duration_seconds": 1
  },
  "soft_threshold": {
    "limit": 1,
    "action": "notify"
  },
  "hard_threshold": {
    "limit": 1,
    "breach_action": "block_admission"
  },
  "state": "active",
  "version": 1,
  "created_at": "<string>",
  "updated_at": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Update Budget thresholds or state

Changes thresholds or the active/paused state by compare-and-swap: expected_version must equal the Budget’s current version or the request conflicts. Scope, metric, and window are immutable and cannot be patched. Budget configuration is snapshotted by each claim, so an edit governs later claims only and never retroactively changes an in-flight reservation. Send Idempotency-Key for safe retries.

Checkfu support posture: alpha; hosted. Required evidence journey: governance-registry. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

PATCH

budgets

{id}

Update Budget thresholds or state

curl --request PATCH \
  --url https://api.checkfu.com/v1/budgets/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "expected_version": 1,
  "soft_threshold": {
    "limit": 1,
    "action": "notify"
  }
}
'

import requests

url = "https://api.checkfu.com/v1/budgets/{id}"

payload = {
    "expected_version": 1,
    "soft_threshold": {
        "limit": 1,
        "action": "notify"
    }
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({expected_version: 1, soft_threshold: {limit: 1, action: 'notify'}})
};

fetch('https://api.checkfu.com/v1/budgets/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/budgets/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'expected_version' => 1,
    'soft_threshold' => [
        'limit' => 1,
        'action' => 'notify'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/budgets/{id}"

	payload := strings.NewReader("{\n  \"expected_version\": 1,\n  \"soft_threshold\": {\n    \"limit\": 1,\n    \"action\": \"notify\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.checkfu.com/v1/budgets/{id}")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expected_version\": 1,\n  \"soft_threshold\": {\n    \"limit\": 1,\n    \"action\": \"notify\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/budgets/{id}")

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

request = Net::HTTP::Patch.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expected_version\": 1,\n  \"soft_threshold\": {\n    \"limit\": 1,\n    \"action\": \"notify\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "workspace_id": "<string>",
  "scope": {
    "kind": "workspace",
    "agent_definition_id": "<unknown>",
    "principal_id": "<unknown>",
    "surface_scope_id": "<unknown>",
    "automation_id": "<unknown>",
    "session_id": "<unknown>"
  },
  "metric": "model_tokens",
  "window": {
    "kind": "rolling",
    "duration_seconds": 1
  },
  "soft_threshold": {
    "limit": 1,
    "action": "notify"
  },
  "hard_threshold": {
    "limit": 1,
    "breach_action": "block_admission"
  },
  "state": "active",
  "version": 1,
  "created_at": "<string>",
  "updated_at": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version

enum<string>

required

Available options:

2026-08-24

idempotency-key

string

Maximum string length: 255

Path Parameters

string

required

Pattern: ^bgt_[0-9a-f]{32}$

Body

application/json

expected_version

integer

required

Required range: x > 0

soft_threshold

object | null

Show child attributes

hard_threshold

object

Show child attributes

state

enum<string>

Available options:

active,

paused

Response

a session_lifetime window only on a session-scoped Budget

string

required

Pattern: ^bgt_[0-9a-f]{32}$

workspace_id

string

required

Pattern: ^wrkspc_[0-9a-f]{32}$

scope

object

required

Show child attributes

metric

enum<string>

required

Available options:

model_tokens,

model_spend,

session_runtime_ms,

total_spend

window

object

required

Option 1
Option 2
Option 3

Show child attributes

soft_threshold

object | null

required

Show child attributes

hard_threshold

object

required

Show child attributes

state

enum<string>

required

Available options:

active,

paused

version

integer

required

Required range: x > 0

created_at

string

required

updated_at

string

required

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Update Budget thresholds or state

Authorizations

Headers

Path Parameters

Body

Response