Catalog

Set the organization's spend budget

Set or replace the ceiling. Requires organization owner or admin.

When the budget is reached, new MCPJam-billed work — chat turns, eval runs, computer starts — is refused for the whole organization until the window resets or an owner or admin raises the cap. Work already in flight finishes, and running computers keep going until they hibernate.

capUsd is stored as whole credits (1 credit = 1 cent), so it is rounded to the cent; the response reports what was kept. Changing the cap mid-window does not reset the spend counter, and does not re-announce a threshold the organization was already told about.

PUT

organizations

{organizationId}

spend-budget

Set the organization's spend budget

curl --request PUT \
  --url https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "capUsd": 1,
  "alertPercents": [
    50
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget"

payload = {
    "capUsd": 1,
    "alertPercents": [50]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({capUsd: 1, alertPercents: [50]})
};

fetch('https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget', 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://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'capUsd' => 1,
    'alertPercents' => [
        50
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget"

	payload := strings.NewReader("{\n  \"capUsd\": 1,\n  \"alertPercents\": [\n    50\n  ]\n}")

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

	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.put("https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"capUsd\": 1,\n  \"alertPercents\": [\n    50\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"capUsd\": 1,\n  \"alertPercents\": [\n    50\n  ]\n}"

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

{
  "capUsd": 123,
  "capCredits": 123,
  "alertPercents": [
    123
  ],
  "spentUsd": 123,
  "spentCredits": 123,
  "windowStartAt": 123,
  "windowEndsAt": 123,
  "alertedPercents": [
    123
  ],
  "capReachedAt": 123,
  "updatedAt": 123,
  "minCapUsd": 123,
  "maxCapUsd": 123,
  "supported": true
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

organizationId

string

required

ID of the organization, from GET /organizations.

Body

application/json

capUsd

number

required

The ceiling in USD, rounded to the cent.

Required range: x >= 0

alertPercents

integer[]

Whole percents of the cap to notify at. Defaults to [80]. 100 is not accepted: reaching the cap always notifies, so listing it would show the same threshold twice.

Required range: 1 <= x <= 99

Response

The stored spend budget.

An organization's ceiling on MCPJam-billed spend for the current billing window. Amounts appear in both USD and credits (1 credit = 1 cent); the credit figures are what the ledger actually stores.

capUsd

number | null

required

The ceiling in USD. null means uncapped.

capCredits

integer | null

required

The same ceiling as the ledger stores it.

alertPercents

integer[]

required

Whole percents of the cap that notify owners and admins. Reaching the cap always notifies, whether or not 100 is listed.

spentUsd

number

required

MCPJam-billed spend so far in this window, in USD.

spentCredits

integer

required

The same spend as the ledger counted it.

windowStartAt

integer

required

Start of the current billing window (epoch ms). Team and enterprise organizations run on their own subscription cycle; everyone else on the UTC month.

windowEndsAt

integer

required

When the window resets and the counter returns to zero (epoch ms).

alertedPercents

integer[]

required

Thresholds already announced this window. Each fires once per window.

capReachedAt

integer | null

required

When the cap was reached this window, or null.

updatedAt

integer | null

required

When the budget was last changed (epoch ms).

minCapUsd

number

required

The smallest budget the platform accepts.

maxCapUsd

number

required

The largest budget the platform accepts.

supported

boolean

required

False for a personal organization, which cannot have a budget.

⌘I

Set the organization's spend budget

curl --request PUT \
  --url https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "capUsd": 1,
  "alertPercents": [
    50
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget"

payload = {
    "capUsd": 1,
    "alertPercents": [50]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({capUsd: 1, alertPercents: [50]})
};

fetch('https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget', 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://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'capUsd' => 1,
    'alertPercents' => [
        50
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget"

	payload := strings.NewReader("{\n  \"capUsd\": 1,\n  \"alertPercents\": [\n    50\n  ]\n}")

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

	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.put("https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"capUsd\": 1,\n  \"alertPercents\": [\n    50\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/organizations/{organizationId}/spend-budget")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"capUsd\": 1,\n  \"alertPercents\": [\n    50\n  ]\n}"

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

{
  "capUsd": 123,
  "capCredits": 123,
  "alertPercents": [
    123
  ],
  "spentUsd": 123,
  "spentCredits": 123,
  "windowStartAt": 123,
  "windowEndsAt": 123,
  "alertedPercents": [
    123
  ],
  "capReachedAt": 123,
  "updatedAt": 123,
  "minCapUsd": 123,
  "maxCapUsd": 123,
  "supported": true
}

API Guides

Endpoints

Set the organization's spend budget

Authorizations

Path Parameters

Body

Response